@tier0/sdk-v2 0.1.0 → 0.2.2

package/dist/esm/data/client.js

@@ -1,14 +1,19 @@
 import { getEnvVar } from '../runtime-env.js';
 import { createBootstrap } from './bootstrap.js';
-import { createDataCall } from './call.js';
+import { createDataTransport } from './call.js';
 import { assertAtomicBatch, Collection, toDoc } from './collection.js';
-import { currentDataSubject } from './context.js';
+import { currentDataSubject, currentSignal } from './context.js';
 import { MAX_COLLECTIONS } from './define.js';
-import { DataError } from './error.js';
+import { createSubscribe } from './subscribe.js';
+import { parseUnsV2Fault, UnsV2Error } from '../uns-v2/client.js';
+import { DataError, toDataError } from './error.js';
 import { validateStepData, validateUpdate } from './schema.js';
 import { toSortPairs } from './sort.js';
+/** Contract limit of `records:queryBatch`. */
+export const MAX_BATCH_QUERIES = 20;
+const QUERY_NAME = /^[A-Za-z0-9_.-]{1,64}$/;
 export function createDataClient(config) {
-    const call = createDataCall(config);
+    const { call, openStream } = createDataTransport(config);
     const environment = config.environment ?? (getEnvVar('NODE_ENV') === 'production' ? 'deployed' : 'preview');
     const declared = [...config.collections];
     if (declared.length > MAX_COLLECTIONS) {
@@ -27,6 +32,7 @@ export function createDataClient(config) {
         resolve: (target) => bootstrap.resolve(lookup(target)),
         recover: bootstrap.recover,
         subject: currentDataSubject,
+        signal: currentSignal,
     };
     const handles = new Map();
     function lookup(target) {
@@ -61,10 +67,14 @@ export function createDataClient(config) {
         const expected = options.dryRun ? 'validated' : 'committed';
         if (result.status !== expected) {
             const failed = results.filter((item) => item.error);
+            // A sync transaction should only fail whole; map the rest of the Outcome statuses anyway.
+            const execution = result.status === 'unknown' ? 'unknown' : result.status === 'partiallyCommitted' ? 'committed' : 'rolledBack';
             throw new DataError({
                 message: `Transaction ${result.status}: ${failed.map((item) => `${item.opId} ${JSON.stringify(item.error)}`).join('; ') || 'no step committed'}`,
-                status: 409,
+                status: execution === 'unknown' ? 503 : 409,
                 code: 'TRANSACTION_FAILED',
+                execution,
+                attempts: 1,
                 details: { status: result.status, results },
             });
         }
@@ -92,8 +102,80 @@ export function createDataClient(config) {
             mode: 'sync',
             ...(options.dryRun ? { dryRun: true } : {}),
             ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
-        }, { dataSubject: currentDataSubject() });
+        }, { dataSubject: currentDataSubject(), signal: currentSignal() });
     }
-    return { collection: collection, transact, ensure: bootstrap.ensure };
+    async function queryBatch(queries, options = {}) {
+        const names = Object.keys(queries);
+        if (names.length < 1 || names.length > MAX_BATCH_QUERIES) {
+            throw new TypeError(`data.queryBatch takes 1–${MAX_BATCH_QUERIES} queries; got ${names.length}.`);
+        }
+        const bad = names.find((name) => !QUERY_NAME.test(name));
+        if (bad !== undefined)
+            throw new TypeError(`data.queryBatch query name "${bad}" must match ${QUERY_NAME}.`);
+        for (const name of names)
+            lookup(queries[name].collection);
+        // Items resolve their collection IDs inside the recovered call, so a retry uses fresh IDs.
+        const { results } = await bootstrap.recover(async () => {
+            const items = await Promise.all(names.map(async (name) => ({
+                id: name,
+                collectionId: await bootstrap.resolve(queries[name].collection),
+                ...(await queries[name].prepare()),
+            })));
+            return call('recordQueryBatch', { queries: items }, { dataSubject: currentDataSubject(), signal: currentSignal() });
+        });
+        const settled = Object.fromEntries(names.map((name) => {
+            const result = results[name];
+            if (result?.ok === true)
+                return [name, { ok: true, value: queries[name].parse(result.data) }];
+            return [name, { ok: false, error: itemError(name, result?.error) }];
+        }));
+        if (options.settle)
+            return settled;
+        const failed = names.find((name) => !settled[name].ok);
+        if (failed !== undefined)
+            throw settled[failed].error;
+        return Object.fromEntries(names.map((name) => [name, settled[name].value]));
+    }
+    const subscribe = createSubscribe({
+        openStream,
+        ensure: bootstrap.ensure,
+        rebuild: bootstrap.rebuild,
+        lookup,
+        declared,
+        subject: currentDataSubject,
+    });
+    return {
+        collection: collection,
+        transact,
+        queryBatch: queryBatch,
+        subscribe,
+        ensure: bootstrap.ensure,
+    };
+}
+/** Item errors carry no HTTP status of their own; it follows from the code. */
+const ITEM_STATUS = { FORBIDDEN: 403, NOT_FOUND: 404 };
+/** A queryBatch item's error as a DataError; its `upstreamStatus` is the status its code stands for. */
+function itemError(name, value) {
+    const fault = parseUnsV2Fault(value);
+    if (!fault) {
+        return new DataError({
+            message: `UNS answered query "${name}" of recordQueryBatch with an invalid result.`,
+            status: 502,
+            code: 'DATA_BAD_RESPONSE',
+            upstreamStatus: 200,
+            execution: 'rolledBack',
+            attempts: 1,
+        });
+    }
+    const error = new UnsV2Error(fault.reason ?? fault.code, {
+        ...fault,
+        // The items are reads: never an unknown outcome.
+        execution: fault.execution === 'unknown' ? 'rolledBack' : fault.execution,
+        queryId: fault.queryId ?? name,
+        status: ITEM_STATUS[fault.code] ?? 400,
+        operation: 'recordQueryBatch',
+        data: { queryId: fault.queryId ?? name, details: fault.details ?? [] },
+    });
+    return toDataError(error);
 }
 //# sourceMappingURL=client.js.map

package/dist/esm/data/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/data/client.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Data client factory: collection handles, cross-collection transactions and\n * the shared bootstrap. An App builds one client per process from its\n * collection declarations; tests build their own with a mock `fetch`.\n */\nimport type { z } from 'zod';\nimport type { ClientConfig } from '../openapi/client.js';\nimport { getEnvVar } from '../runtime-env.js';\nimport { createBootstrap, type DataEnvironment, type EnsureState, type Logger } from './bootstrap.js';\nimport { createDataCall } from './call.js';\nimport { assertAtomicBatch, Collection, toDoc, type UnsRecord, type WithMeta } from './collection.js';\nimport { currentDataSubject } from './context.js';\nimport { MAX_COLLECTIONS, type CollectionDefinition } from './define.js';\nimport { DataError } from './error.js';\nimport { validateStepData, validateUpdate } from './schema.js';\nimport { toSortPairs, type Filter, type Sort } from './sort.js';\n\nexport type TransactAction =\n  | 'record.create'\n  | 'record.check'\n  | 'record.read'\n  | 'record.update'\n  | 'record.modify'\n  | 'record.replace'\n  | 'record.delete'\n  | 'record.query';\n\n/** One `recordTransactionExecute` item; `collection` is a declaration or alias instead of a collection ID. */\nexport interface TransactStep {\n  opId: string;\n  action: TransactAction;\n  collection: CollectionDefinition | string;\n  id?: string | { ref: string };\n  filter?: Filter;\n  data?: Record<string, unknown>;\n  update?: Record<string, unknown>;\n  upsert?: boolean;\n  expectedRevision?: number;\n  dependsOn?: string[];\n  bindings?: { path: string; ref: string; resultPath: string }[];\n  selection?: 'exactOne' | 'first';\n  sort?: Sort;\n  returnDocument?: 'before' | 'after';\n  exists?: boolean;\n  operations?: Record<string, unknown>[];\n  conditions?: Filter[];\n  /** `record.query`: rows to bind from; `expectCount` asserts the match count before `limit`. */\n  query?: { filter?: Filter; sort?: Sort; limit?: number; expectCount?: { min?: number; max?: number } };\n  arrayFilters?: Record<string, unknown>[];\n}\n\nexport interface TransactResultItem {\n  opId: string;\n  action: string;\n  id: string;\n  status: string;\n  collectionId?: string;\n  revision?: number;\n  /** Before/after snapshot when requested, as a flat document. */\n  document?: WithMeta<Record<string, unknown>>;\n  data?: unknown;\n  query?: unknown;\n  error?: unknown;\n}\n\nexport interface TransactResult {\n  status: string;\n  results: TransactResultItem[];\n}\n\n/** Credentials as for `createClient`; `transportTimeoutMs` defaults to 15 s here, the UNS statement timeout. */\nexport interface DataClientConfig extends ClientConfig {\n  collections: readonly CollectionDefinition[];\n  /** Defaults to \"deployed\" when NODE_ENV is production, otherwise \"preview\". */\n  environment?: DataEnvironment;\n  logger?: Logger;\n}\n\nexport interface DataClient {\n  /** Typed handle for a declaration listed in `collections`. */\n  collection<C extends CollectionDefinition>(definition: C): Collection<z.output<C['schema']>, z.input<C['schema']>>;\n  /** Handle by alias, typed by the caller. */\n  collection<T extends object = Record<string, unknown>>(alias: string): Collection<T>;\n  /**\n   * Atomic multi-record, multi-collection write (`recordTransactionExecute`, sync),\n   * at most 200 steps. Steps can depend on each other (`dependsOn`) and bind\n   * earlier results (`bindings`). This is not a Mongo session: everything is\n   * sent at once.\n   */\n  transact(steps: readonly TransactStep[], options?: { dryRun?: boolean; idempotencyKey?: string }): Promise<TransactResult>;\n  /** Ensures every declaration now (normally lazy on first access). */\n  ensure(): Promise<EnsureState>;\n}\n\nexport function createDataClient(config: DataClientConfig): DataClient {\n  const call = createDataCall(config);\n  const environment = config.environment ?? (getEnvVar('NODE_ENV') === 'production' ? 'deployed' : 'preview');\n  const declared = [...config.collections];\n  if (declared.length > MAX_COLLECTIONS) {\n    throw new Error(`An App declares at most ${MAX_COLLECTIONS} collections; got ${declared.length}.`);\n  }\n  const seen = new Set<string>();\n  for (const definition of declared) {\n    const key = definition.alias.toLowerCase();\n    if (seen.has(key)) throw new Error(`Collection alias \"${definition.alias}\" is declared twice (aliases are case-insensitive).`);\n    seen.add(key);\n  }\n\n  const bootstrap = createBootstrap({ call, collections: declared, environment, logger: config.logger ?? console });\n  const runtime = {\n    call,\n    resolve: (target: CollectionDefinition | string) => bootstrap.resolve(lookup(target)),\n    recover: bootstrap.recover,\n    subject: currentDataSubject,\n  };\n  const handles = new Map<CollectionDefinition, Collection<object>>();\n\n  function lookup(target: CollectionDefinition | string): CollectionDefinition {\n    if (typeof target === 'string') {\n      const found = declared.find((definition) => definition.alias.toLowerCase() === target.toLowerCase());\n      if (!found) throw new Error(`Collection \"${target}\" is not declared in this data client's collections.`);\n      return found;\n    }\n    if (!declared.includes(target)) {\n      throw new Error(`Collection \"${target.alias}\" is declared but missing from the \\`collections\\` passed to createDataClient.`);\n    }\n    return target;\n  }\n\n  function collection(target: CollectionDefinition | string) {\n    const definition = lookup(target);\n    let handle = handles.get(definition);\n    if (!handle) {\n      handle = new Collection<object>(definition, runtime);\n      handles.set(definition, handle);\n    }\n    return handle;\n  }\n\n  async function transact(\n    steps: readonly TransactStep[],\n    options: { dryRun?: boolean; idempotencyKey?: string } = {},\n  ): Promise<TransactResult> {\n    assertAtomicBatch('data.transact', steps.length);\n    // Steps resolve their collection IDs inside the recovered call, so a retry uses fresh IDs.\n    const result = await bootstrap.recover(() => sendTransaction(steps, options));\n    const results = (result.results ?? []).map(({ document, ...item }) => ({\n      ...item,\n      ...(document ? { document: toDoc<Record<string, unknown>>(document) } : {}),\n    }));\n    const expected = options.dryRun ? 'validated' : 'committed';\n    if (result.status !== expected) {\n      const failed = results.filter((item) => item.error);\n      throw new DataError({\n        message: `Transaction ${result.status}: ${failed.map((item) => `${item.opId} ${JSON.stringify(item.error)}`).join('; ') || 'no step committed'}`,\n        status: 409,\n        code: 'TRANSACTION_FAILED',\n        details: { status: result.status, results },\n      });\n    }\n    return { status: result.status, results };\n  }\n\n  async function sendTransaction(steps: readonly TransactStep[], options: { dryRun?: boolean; idempotencyKey?: string }) {\n    const items = await Promise.all(\n      steps.map(async ({ collection: target, sort, query, ...step }) => {\n        const definition = lookup(target);\n        const item: Record<string, unknown> = { ...step, collectionId: await bootstrap.resolve(definition) };\n        if (sort) item.sort = toSortPairs(sort);\n        if (query) item.query = { ...query, ...(query.sort ? { sort: toSortPairs(query.sort) } : {}) };\n        if (step.data) {\n          // Fields bound to earlier results are filled by UNS at commit; everything literal validates now.\n          const bound = (step.bindings ?? []).flatMap((binding) => (binding.path.startsWith('data.') ? [binding.path.slice(5).split('.')[0]] : []));\n          item.data = validateStepData(definition, step.data, bound);\n        }\n        if (step.update) item.update = validateUpdate(definition, step.update);\n        return item;\n      }),\n    );\n    return call<{ status: string; results?: (Omit<TransactResultItem, 'document'> & { document?: UnsRecord })[] }>(\n      'recordTransactionExecute',\n      {\n        items,\n        mode: 'sync',\n        ...(options.dryRun ? { dryRun: true } : {}),\n        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),\n      },\n      { dataSubject: currentDataSubject() },\n    );\n  }\n\n  return { collection: collection as DataClient['collection'], transact, ensure: bootstrap.ensure };\n}\n"]}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/data/client.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Data client factory: collection handles, cross-collection transactions and\n * the shared bootstrap. An App builds one client per process from its\n * collection declarations; tests build their own with a mock `fetch`.\n */\nimport type { z } from 'zod';\nimport type { ClientConfig } from '../openapi/client.js';\nimport { getEnvVar } from '../runtime-env.js';\nimport { createBootstrap, type DataEnvironment, type EnsureState, type Logger } from './bootstrap.js';\nimport { createDataTransport } from './call.js';\nimport { assertAtomicBatch, Collection, toDoc, type BatchQuery, type UnsRecord, type WithMeta } from './collection.js';\nimport { currentDataSubject, currentSignal } from './context.js';\nimport { MAX_COLLECTIONS, type CollectionDefinition } from './define.js';\nimport { createSubscribe, type SubscribeOptions, type SubscriptionEvent } from './subscribe.js';\nimport { parseUnsV2Fault, UnsV2Error } from '../uns-v2/client.js';\nimport { DataError, toDataError } from './error.js';\nimport { validateStepData, validateUpdate } from './schema.js';\nimport { toSortPairs, type Filter, type Sort } from './sort.js';\n\nexport type TransactAction =\n  | 'record.create'\n  | 'record.check'\n  | 'record.read'\n  | 'record.update'\n  | 'record.modify'\n  | 'record.replace'\n  | 'record.delete'\n  | 'record.query';\n\n/** One `recordTransactionExecute` item; `collection` is a declaration or alias instead of a collection ID. */\nexport interface TransactStep {\n  opId: string;\n  action: TransactAction;\n  collection: CollectionDefinition | string;\n  id?: string | { ref: string };\n  filter?: Filter;\n  data?: Record<string, unknown>;\n  update?: Record<string, unknown>;\n  upsert?: boolean;\n  expectedRevision?: number;\n  dependsOn?: string[];\n  bindings?: { path: string; ref: string; resultPath: string }[];\n  selection?: 'exactOne' | 'first';\n  sort?: Sort;\n  returnDocument?: 'before' | 'after';\n  exists?: boolean;\n  operations?: Record<string, unknown>[];\n  conditions?: Filter[];\n  /** `record.query`: rows to bind from; `expectCount` asserts the match count before `limit`. */\n  query?: { filter?: Filter; sort?: Sort; limit?: number; expectCount?: { min?: number; max?: number } };\n  arrayFilters?: Record<string, unknown>[];\n}\n\nexport interface TransactResultItem {\n  opId: string;\n  action: string;\n  id: string;\n  status: string;\n  collectionId?: string;\n  revision?: number;\n  /** Before/after snapshot when requested, as a flat document. */\n  document?: WithMeta<Record<string, unknown>>;\n  data?: unknown;\n  query?: unknown;\n  error?: unknown;\n}\n\nexport interface TransactResult {\n  status: string;\n  results: TransactResultItem[];\n}\n\n/** Named reads for `data.queryBatch`: 1–20 entries, names matching `[A-Za-z0-9_.-]{1,64}`. */\nexport type BatchQueries = Record<string, BatchQuery<unknown>>;\nexport type BatchResults<Q extends BatchQueries> = { [K in keyof Q]: Q[K] extends BatchQuery<infer R> ? R : never };\nexport type SettledBatchResults<Q extends BatchQueries> = {\n  [K in keyof Q]: Q[K] extends BatchQuery<infer R> ? { ok: true; value: R } | { ok: false; error: DataError } : never;\n};\n\n/** Contract limit of `records:queryBatch`. */\nexport const MAX_BATCH_QUERIES = 20;\nconst QUERY_NAME = /^[A-Za-z0-9_.-]{1,64}$/;\n\n/** Credentials as for `createClient`; `transportTimeoutMs` (per attempt) defaults to 25 s here, see DEFAULT_DATA_TIMEOUT_MS. */\nexport interface DataClientConfig extends ClientConfig {\n  collections: readonly CollectionDefinition[];\n  /** Defaults to \"deployed\" when NODE_ENV is production, otherwise \"preview\". */\n  environment?: DataEnvironment;\n  logger?: Logger;\n}\n\nexport interface DataClient {\n  /** Typed handle for a declaration listed in `collections`. */\n  collection<C extends CollectionDefinition>(definition: C): Collection<z.output<C['schema']>, z.input<C['schema']>>;\n  /** Handle by alias, typed by the caller. */\n  collection<T extends object = Record<string, unknown>>(alias: string): Collection<T>;\n  /**\n   * Atomic multi-record, multi-collection write (`recordTransactionExecute`, sync),\n   * at most 200 steps. Steps can depend on each other (`dependsOn`) and bind\n   * earlier results (`bindings`). This is not a Mongo session: everything is\n   * sent at once.\n   */\n  transact(steps: readonly TransactStep[], options?: { dryRun?: boolean; idempotencyKey?: string }): Promise<TransactResult>;\n  /**\n   * Committed record changes of declared collections (all by default), as\n   * one async iterable that reconnects and resumes by itself; see\n   * `SubscribeOptions`. Events carry identities only; changes in collections\n   * with employee data rules arrive as collection-level notices unless\n   * `restricted: \"record\"` is asked for. Open it inside a request to watch as\n   * that employee, or in `runAsApp` for one App-wide stream a server fans out.\n   */\n  subscribe(options?: SubscribeOptions): AsyncIterable<SubscriptionEvent>;\n  /**\n   * Up to 20 reads of declared collections in one request, answered from one\n   * snapshot: what a page shows (a list page with its total, counters, a\n   * lookup by ID) in one round trip. Build each read with\n   * `collection.query.*`; results come back under the same names.\n   *\n   * A read UNS refuses on its own (invalid filter, no grant) rejects the\n   * whole call with its DataError; with `{ settle: true }` every result is\n   * `{ ok, value }` or `{ ok: false, error }` instead. A statement timeout or\n   * a batch over 2000 rows / 8 MiB always fails the whole call.\n   */\n  queryBatch<Q extends BatchQueries>(queries: Q): Promise<BatchResults<Q>>;\n  queryBatch<Q extends BatchQueries>(queries: Q, options: { settle: true }): Promise<SettledBatchResults<Q>>;\n  /** Ensures every declaration now (normally lazy on first access). */\n  ensure(): Promise<EnsureState>;\n}\n\nexport function createDataClient(config: DataClientConfig): DataClient {\n  const { call, openStream } = createDataTransport(config);\n  const environment = config.environment ?? (getEnvVar('NODE_ENV') === 'production' ? 'deployed' : 'preview');\n  const declared = [...config.collections];\n  if (declared.length > MAX_COLLECTIONS) {\n    throw new Error(`An App declares at most ${MAX_COLLECTIONS} collections; got ${declared.length}.`);\n  }\n  const seen = new Set<string>();\n  for (const definition of declared) {\n    const key = definition.alias.toLowerCase();\n    if (seen.has(key)) throw new Error(`Collection alias \"${definition.alias}\" is declared twice (aliases are case-insensitive).`);\n    seen.add(key);\n  }\n\n  const bootstrap = createBootstrap({ call, collections: declared, environment, logger: config.logger ?? console });\n  const runtime = {\n    call,\n    resolve: (target: CollectionDefinition | string) => bootstrap.resolve(lookup(target)),\n    recover: bootstrap.recover,\n    subject: currentDataSubject,\n    signal: currentSignal,\n  };\n  const handles = new Map<CollectionDefinition, Collection<object>>();\n\n  function lookup(target: CollectionDefinition | string): CollectionDefinition {\n    if (typeof target === 'string') {\n      const found = declared.find((definition) => definition.alias.toLowerCase() === target.toLowerCase());\n      if (!found) throw new Error(`Collection \"${target}\" is not declared in this data client's collections.`);\n      return found;\n    }\n    if (!declared.includes(target)) {\n      throw new Error(`Collection \"${target.alias}\" is declared but missing from the \\`collections\\` passed to createDataClient.`);\n    }\n    return target;\n  }\n\n  function collection(target: CollectionDefinition | string) {\n    const definition = lookup(target);\n    let handle = handles.get(definition);\n    if (!handle) {\n      handle = new Collection<object>(definition, runtime);\n      handles.set(definition, handle);\n    }\n    return handle;\n  }\n\n  async function transact(\n    steps: readonly TransactStep[],\n    options: { dryRun?: boolean; idempotencyKey?: string } = {},\n  ): Promise<TransactResult> {\n    assertAtomicBatch('data.transact', steps.length);\n    // Steps resolve their collection IDs inside the recovered call, so a retry uses fresh IDs.\n    const result = await bootstrap.recover(() => sendTransaction(steps, options));\n    const results = (result.results ?? []).map(({ document, ...item }) => ({\n      ...item,\n      ...(document ? { document: toDoc<Record<string, unknown>>(document) } : {}),\n    }));\n    const expected = options.dryRun ? 'validated' : 'committed';\n    if (result.status !== expected) {\n      const failed = results.filter((item) => item.error);\n      // A sync transaction should only fail whole; map the rest of the Outcome statuses anyway.\n      const execution = result.status === 'unknown' ? 'unknown' : result.status === 'partiallyCommitted' ? 'committed' : 'rolledBack';\n      throw new DataError({\n        message: `Transaction ${result.status}: ${failed.map((item) => `${item.opId} ${JSON.stringify(item.error)}`).join('; ') || 'no step committed'}`,\n        status: execution === 'unknown' ? 503 : 409,\n        code: 'TRANSACTION_FAILED',\n        execution,\n        attempts: 1,\n        details: { status: result.status, results },\n      });\n    }\n    return { status: result.status, results };\n  }\n\n  async function sendTransaction(steps: readonly TransactStep[], options: { dryRun?: boolean; idempotencyKey?: string }) {\n    const items = await Promise.all(\n      steps.map(async ({ collection: target, sort, query, ...step }) => {\n        const definition = lookup(target);\n        const item: Record<string, unknown> = { ...step, collectionId: await bootstrap.resolve(definition) };\n        if (sort) item.sort = toSortPairs(sort);\n        if (query) item.query = { ...query, ...(query.sort ? { sort: toSortPairs(query.sort) } : {}) };\n        if (step.data) {\n          // Fields bound to earlier results are filled by UNS at commit; everything literal validates now.\n          const bound = (step.bindings ?? []).flatMap((binding) => (binding.path.startsWith('data.') ? [binding.path.slice(5).split('.')[0]] : []));\n          item.data = validateStepData(definition, step.data, bound);\n        }\n        if (step.update) item.update = validateUpdate(definition, step.update);\n        return item;\n      }),\n    );\n    return call<{ status: string; results?: (Omit<TransactResultItem, 'document'> & { document?: UnsRecord })[] }>(\n      'recordTransactionExecute',\n      {\n        items,\n        mode: 'sync',\n        ...(options.dryRun ? { dryRun: true } : {}),\n        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),\n      },\n      { dataSubject: currentDataSubject(), signal: currentSignal() },\n    );\n  }\n\n  async function queryBatch<Q extends BatchQueries>(queries: Q, options: { settle?: boolean } = {}) {\n    const names = Object.keys(queries);\n    if (names.length < 1 || names.length > MAX_BATCH_QUERIES) {\n      throw new TypeError(`data.queryBatch takes 1–${MAX_BATCH_QUERIES} queries; got ${names.length}.`);\n    }\n    const bad = names.find((name) => !QUERY_NAME.test(name));\n    if (bad !== undefined) throw new TypeError(`data.queryBatch query name \"${bad}\" must match ${QUERY_NAME}.`);\n    for (const name of names) lookup(queries[name].collection);\n    // Items resolve their collection IDs inside the recovered call, so a retry uses fresh IDs.\n    const { results } = await bootstrap.recover(async () => {\n      const items = await Promise.all(names.map(async (name) => ({\n        id: name,\n        collectionId: await bootstrap.resolve(queries[name].collection),\n        ...(await queries[name].prepare()),\n      })));\n      return call<{ results: Record<string, { ok: true; data: unknown } | { ok: false; error: unknown }> }>(\n        'recordQueryBatch', { queries: items }, { dataSubject: currentDataSubject(), signal: currentSignal() });\n    });\n    const settled = Object.fromEntries(names.map((name) => {\n      const result = results[name];\n      if (result?.ok === true) return [name, { ok: true, value: queries[name].parse(result.data) }];\n      return [name, { ok: false, error: itemError(name, result?.error) }];\n    })) as Record<string, { ok: true; value: unknown } | { ok: false; error: DataError }>;\n    if (options.settle) return settled;\n    const failed = names.find((name) => !settled[name].ok);\n    if (failed !== undefined) throw (settled[failed] as { error: DataError }).error;\n    return Object.fromEntries(names.map((name) => [name, (settled[name] as { value: unknown }).value]));\n  }\n\n  const subscribe = createSubscribe({\n    openStream,\n    ensure: bootstrap.ensure,\n    rebuild: bootstrap.rebuild,\n    lookup,\n    declared,\n    subject: currentDataSubject,\n  });\n\n  return {\n    collection: collection as DataClient['collection'],\n    transact,\n    queryBatch: queryBatch as DataClient['queryBatch'],\n    subscribe,\n    ensure: bootstrap.ensure,\n  };\n}\n\n/** Item errors carry no HTTP status of their own; it follows from the code. */\nconst ITEM_STATUS: Record<string, number> = { FORBIDDEN: 403, NOT_FOUND: 404 };\n\n/** A queryBatch item's error as a DataError; its `upstreamStatus` is the status its code stands for. */\nfunction itemError(name: string, value: unknown): DataError {\n  const fault = parseUnsV2Fault(value);\n  if (!fault) {\n    return new DataError({\n      message: `UNS answered query \"${name}\" of recordQueryBatch with an invalid result.`,\n      status: 502,\n      code: 'DATA_BAD_RESPONSE',\n      upstreamStatus: 200,\n      execution: 'rolledBack',\n      attempts: 1,\n    });\n  }\n  const error = new UnsV2Error(fault.reason ?? fault.code, {\n    ...fault,\n    // The items are reads: never an unknown outcome.\n    execution: fault.execution === 'unknown' ? 'rolledBack' : fault.execution,\n    queryId: fault.queryId ?? name,\n    status: ITEM_STATUS[fault.code] ?? 400,\n    operation: 'recordQueryBatch',\n    data: { queryId: fault.queryId ?? name, details: fault.details ?? [] },\n  });\n  return toDataError(error);\n}\n\n"]}

package/dist/esm/data/collection.d.ts

@@ -12,6 +12,12 @@ export type WithMeta<T> = T & {
     _id: string;
     _meta: RecordMeta;
 };
+/** A projection may omit business fields at any depth; array and tuple containers retain their shape. */
+export type DeepPartial<T> = T extends readonly unknown[] ? {
+    [K in keyof T]: DeepPartial<T[K]>;
+} : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 export type Projection = Record<string, 0 | 1 | boolean>;
 export type Update = Record<string, unknown>;
 export interface UnsRecord {
@@ -39,6 +45,8 @@ export interface CollectionRuntime {
     }): Promise<R>;
     /** Data subject of the request being served. */
     subject(): string | undefined;
+    /** Abort signal of the request being served. */
+    signal(): AbortSignal | undefined;
 }
 /** Rejects batches UNS would refuse, before anything is sent. */
 export declare function assertAtomicBatch(operation: string, count: number): void;
@@ -83,6 +91,64 @@ export interface FindPageOptions {
     /** At most 200. */
     pageSize?: number;
     projection?: Projection;
+    /** Count matches up to this many (1–100000); UNS defaults to 10000. */
+    maxCount?: number;
+}
+/** A match count UNS stopped at its limit: `capped` means "at least `count`". */
+export interface CappedCount {
+    count: number;
+    capped: boolean;
+}
+/** UNS reads at most 100 records by ID per request. */
+export declare const MAX_GET_IDS = 100;
+export interface FoundPage<T> {
+    items: WithMeta<T>[];
+    total: CappedCount;
+    page: number;
+    pageSize: number;
+}
+export interface ValueCount {
+    value: unknown;
+    count: number;
+}
+/** One read of `data.queryBatch`, built by `collection.query.*`. */
+export interface BatchQuery<R> {
+    readonly collection: CollectionDefinition;
+    /** The batch item without `id` and `collectionId`; resolves `$lookup` targets. */
+    prepare(): Promise<Record<string, unknown>>;
+    /** The item's result as the builder's caller sees it. */
+    parse(data: unknown): R;
+}
+export interface CollectionQueries<T> {
+    /** First page (≤200, default 20); `maxCount` adds the capped total of all matches. */
+    find(filter?: Filter, options?: {
+        sort?: Sort;
+        limit?: number;
+        projection?: Projection;
+        maxCount?: number;
+    }): BatchQuery<{
+        items: WithMeta<T>[];
+        hasMore: boolean;
+        total?: CappedCount;
+    }>;
+    /** Like `collection.findPage`. */
+    findPage(filter?: Filter, options?: FindPageOptions): BatchQuery<FoundPage<T>>;
+    count(filter?: Filter, options?: {
+        maxCount?: number;
+    }): BatchQuery<CappedCount>;
+    /** The 200 most frequent values. */
+    countBy(field: string, filter?: Filter): BatchQuery<ValueCount[]>;
+    /** The first 200 distinct values. */
+    distinct(field: string, filter?: Filter): BatchQuery<unknown[]>;
+    /** The first 200 output rows. */
+    aggregate<R = Record<string, unknown>>(pipeline: Record<string, unknown>[]): BatchQuery<R[]>;
+    /** 1–100 distinct records by ID, as `collection.get`. */
+    get(ids: readonly string[], options?: {
+        projection?: Projection;
+    }): BatchQuery<{
+        items: WithMeta<T>[];
+        missing: string[];
+    }>;
 }
 export interface UpdateOptions {
     upsert?: boolean;
@@ -96,6 +162,15 @@ export interface FindOneAndOptions extends UpdateOptions {
     returnDocument?: 'before' | 'after';
     projection?: Projection;
 }
+export type InsertOneOptions = {
+    idempotencyKey?: string;
+} & ({
+    returnDocument?: 'none';
+    projection?: never;
+} | {
+    returnDocument: 'after';
+    projection?: Projection;
+});
 export type BulkOperation = {
     insertOne: {
         document: Record<string, unknown>;
@@ -135,16 +210,43 @@ export declare class Collection<T extends object = Record<string, unknown>, TInp
     find(filter?: Filter, options?: FindOptions): Cursor<WithMeta<T>>;
     findOne(filter?: Filter, options?: Omit<FindOptions, 'limit'>): Promise<WithMeta<T> | null>;
     /**
-     * One numbered page plus the total match count, for paged list screens.
-     * Uses `recordAggregatePipeline` offset paging.
+     * Records by ID, in the order asked for (each ID once, at its first
+     * position); IDs that do not exist, are deleted or are hidden by employee
+     * data rules are listed in `missing` alike. More than 100 IDs are read in
+     * chunks of 100 (not one snapshot).
      */
-    findPage(filter?: Filter, options?: FindPageOptions): Promise<{
+    get(ids: readonly string[], options?: {
+        projection?: Projection;
+    }): Promise<{
         items: WithMeta<T>[];
-        total: number;
-        page: number;
-        pageSize: number;
+        missing: string[];
     }>;
-    countDocuments(filter?: Filter): Promise<number>;
+    /**
+     * One numbered page plus the total match count, for paged list screens:
+     * one `recordAggregatePipeline` offset page whose `count` runs in the same
+     * snapshot. Show a capped total as "10000+".
+     */
+    findPage(filter?: Filter, options?: FindPageOptions): Promise<FoundPage<T>>;
+    /**
+     * Counts matches up to `maxCount` (1–100000, UNS default 100000). A
+     * `capped` result means "at least `count`".
+     */
+    countDocuments(filter?: Filter, options?: {
+        maxCount?: number;
+    }): Promise<CappedCount>;
+    /**
+     * Match counts per value of `field`, largest first: one `$group` pipeline
+     * instead of a count per value. Records without the field count under
+     * `value: null`.
+     */
+    countBy(field: string, filter?: Filter): Promise<ValueCount[]>;
+    /**
+     * Builders for `data.queryBatch`: each describes one read of this
+     * collection, run together with the others in one request and one
+     * snapshot. Each returns one page (at most 200 rows), unlike the cursor
+     * methods; `get` takes at most 100 IDs.
+     */
+    get query(): CollectionQueries<T>;
     /** Distinct values of a field (every page). */
     distinct(field: string, filter?: Filter): Promise<unknown[]>;
     /**
@@ -163,12 +265,37 @@ export declare class Collection<T extends object = Record<string, unknown>, TInp
     private aggregatePage;
     /** Converts Mongo-style `$sort` objects and resolves `$lookup.from`, recursively. */
     private prepareStages;
+    /** Returns the creation snapshot in the same write; replay preserves that snapshot and requires current read access. */
     insertOne(document: TInput & {
         _id?: string;
-    }, options?: {
-        idempotencyKey?: string;
+    }, options: Extract<InsertOneOptions, {
+        returnDocument: 'after';
+    }> & {
+        projection?: never;
     }): Promise<{
         insertedId: string;
+        value: WithMeta<T>;
+    }>;
+    insertOne(document: TInput & {
+        _id?: string;
+    }, options: Extract<InsertOneOptions, {
+        returnDocument: 'after';
+    }>): Promise<{
+        insertedId: string;
+        value: WithMeta<DeepPartial<T>>;
+    }>;
+    insertOne(document: TInput & {
+        _id?: string;
+    }, options?: Extract<InsertOneOptions, {
+        returnDocument?: 'none';
+    }>): Promise<{
+        insertedId: string;
+    }>;
+    insertOne(document: TInput & {
+        _id?: string;
+    }, options: InsertOneOptions): Promise<{
+        insertedId: string;
+        value?: WithMeta<DeepPartial<T>>;
     }>;
     /** Inserts up to 200 documents atomically (all or none). */
     insertMany(documents: readonly (TInput & {
@@ -187,13 +314,20 @@ export declare class Collection<T extends object = Record<string, unknown>, TInp
     /**
      * Updates every match like Mongo's updateMany: documents commit one by one
      * (not atomically), following `resumeAfter` until every match is processed.
-     * A failure stops the run and reports the counts already committed. For
-     * all-or-nothing multi-document changes use `data.transact` (≤200 items).
+     * A failure after some documents committed keeps its code but is
+     * `execution: "committed"`, with the cumulative counts and
+     * `details.resumeAfter`; pass that back as `resumeAfter` to continue
+     * instead of repeating the call. For all-or-nothing multi-document changes
+     * use `data.transact` (≤200 items).
      */
-    updateMany(filter: Filter, update: Update, options?: Pick<UpdateOptions, 'arrayFilters'>): Promise<{
+    updateMany(filter: Filter, update: Update, options?: Pick<UpdateOptions, 'arrayFilters'> & {
+        resumeAfter?: string;
+    }): Promise<{
         matchedCount: number;
         modifiedCount: number;
     }>;
+    /** Runs a non-atomic many-write page by page; see updateMany for failures. */
+    private writeEach;
     /**
      * Replaces the whole body. Fields written by another App version and not in
      * this declaration are lost — prefer `updateOne` with `$set`.
@@ -209,9 +343,12 @@ export declare class Collection<T extends object = Record<string, unknown>, TInp
     }>;
     /**
      * Soft-deletes every match, one document at a time like Mongo's deleteMany
-     * (not atomic), following `resumeAfter`; requires `uns.delete` on the App key.
+     * (not atomic), following `resumeAfter`; requires `uns.delete` on the App
+     * key. Failures after committed deletes report them as updateMany does.
      */
-    deleteMany(filter: Filter): Promise<{
+    deleteMany(filter: Filter, options?: {
+        resumeAfter?: string;
+    }): Promise<{
         deletedCount: number;
     }>;
     /**