Read Semantics

SDK read methods share a few behavior patterns across client.thing, client.shape, and repository list calls. Use the generated WarmHubClient API reference for exact signatures.

Match Patterns

The match option accepts a glob pattern that filters against full wrefs such as Location/cave.

• * matches a single path segment.
• ** matches zero or more path segments.

await client.thing.head('acme', 'world', {
  match: 'Location/dungeon/*',
})

await client.thing.about('acme', 'world', 'Location/cave', {
  match: 'Belief/**',
})

Reads with a match filter may lag briefly after a write while WarmHub updates read indexes. Subsequent reads after the index catches up will see the new state.

Batch Reads

client.thing.getMany(...) accepts any number of wrefs and auto-chunks requests above the backend’s 500-wref transport cap.

The result preserves duplicates: each duplicate counts toward the requested count and produces a duplicate result or missing entry. Dedupe upstream when you want one row per unique wref.

The optional top-level version pins every requested wref that does not already include @vN or @HEAD. Per-wref pins remain intact.

Missing and inaccessible refs are reported in missing rather than throwing per item. With includeRetracted: true, retracted records can appear in items; without it, retracted refs land in missing.

Use chunkSize when you want smaller backend requests for memory or latency shaping; values above 500 are clamped to the transport cap. Use chunkConcurrency to run multiple chunks in parallel while keeping the merged result order deterministic.

Reference Queries

client.thing.refs(...) queries wref-typed fields.

• Inbound refs find records whose wref fields point to the supplied wref.
• Outbound refs find records the supplied record points to.
• Inbound queries can be narrowed to a field path.

Use client.thing.about(...) for assertions about a thing or collection target. Use refs(...) when you specifically need field-level wref links.

Search Modes

client.thing.search(...) supports text, vector, and hybrid modes.

Mode	Behavior
text	Full-text search and the full read-filter set
vector	Embedding-based semantic search
hybrid	Combined text and vector search

See the WarmHubClient API reference for the per-mode option set.

When searching with an assertion target or collection resolution, pages may be sparse. Keep paginating until nextCursor is absent.

Pagination

Paginated methods follow a shared cursor pattern: the request accepts limit and cursor, and the response includes items plus an optional nextCursor.

const page1 = await client.repo.listPage('acme', { limit: 10 })

if (page1.nextCursor) {
  const page2 = await client.repo.listPage('acme', {
    cursor: page1.nextCursor,
    limit: 10,
  })
}

Some methods return a generic page shape and others return method-specific envelopes. The cursor pattern is the same; methods that do not paginate return their full result set in one call.

Iteration

For “scan everything matching this filter” reads, prefer the SDK iterator helpers over manual cursor loops:

for await (const item of client.thing.queryIter('acme', 'world', {
  shape: 'Location',
  limit: 500,
})) {
  console.log(item.wref)
}

thing.refsIter, thing.queryIter, thing.headIter, and thing.aboutIter handle the cursor internally and yield one item at a time. Their *All variants materialize the full scan into an array and accept max to prevent accidental unbounded reads:

const refs = await client.thing.refsAll('acme', 'world', 'Location/cave', {
  direction: 'inbound',
  max: 10_000,
})

The underlying paginated methods remain available when you need explicit page envelopes, nextCursor storage, or custom page scheduling.

Anonymous Pagination Caps

Tokenless clients reading public repositories have narrower paging on shared read procedures:

• limit is capped at 25 items per page.
• Omitted limit defaults to 25.
• The page size is bound to the cursor. Follow-up requests must omit limit or pass the same value used to mint the cursor.
• Anonymous pagination stops after 2 pages for repository list pages, shape history, thing HEAD, thing about, thing query, and wref-form thing history.
• Shape- or about-filtered thing history allows only page 0 anonymously.

The SDK surfaces these boundaries as WarmHubError kinds such as VALIDATION_ERROR or UNAUTHENTICATED. REST query endpoints can collapse equivalent deny paths to opaque 404 responses to keep repository existence private.

Authenticated callers see no anonymous pagination narrowing.