@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/dist/cjs/data/client.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BATCH_QUERIES = void 0;
+exports.createDataClient = createDataClient;
+const runtime_env_js_1 = require("../runtime-env.js");
+const bootstrap_js_1 = require("./bootstrap.js");
+const call_js_1 = require("./call.js");
+const collection_js_1 = require("./collection.js");
+const context_js_1 = require("./context.js");
+const define_js_1 = require("./define.js");
+const subscribe_js_1 = require("./subscribe.js");
+const client_js_1 = require("../uns-v2/client.js");
+const error_js_1 = require("./error.js");
+const schema_js_1 = require("./schema.js");
+const sort_js_1 = require("./sort.js");
+/** Contract limit of `records:queryBatch`. */
+exports.MAX_BATCH_QUERIES = 20;
+const QUERY_NAME = /^[A-Za-z0-9_.-]{1,64}$/;
+function createDataClient(config) {
+    const { call, openStream } = (0, call_js_1.createDataTransport)(config);
+    const environment = config.environment ?? ((0, runtime_env_js_1.getEnvVar)('NODE_ENV') === 'production' ? 'deployed' : 'preview');
+    const declared = [...config.collections];
+    if (declared.length > define_js_1.MAX_COLLECTIONS) {
+        throw new Error(`An App declares at most ${define_js_1.MAX_COLLECTIONS} collections; got ${declared.length}.`);
+    }
+    const seen = new Set();
+    for (const definition of declared) {
+        const key = definition.alias.toLowerCase();
+        if (seen.has(key))
+            throw new Error(`Collection alias "${definition.alias}" is declared twice (aliases are case-insensitive).`);
+        seen.add(key);
+    }
+    const bootstrap = (0, bootstrap_js_1.createBootstrap)({ call, collections: declared, environment, logger: config.logger ?? console });
+    const runtime = {
+        call,
+        resolve: (target) => bootstrap.resolve(lookup(target)),
+        recover: bootstrap.recover,
+        subject: context_js_1.currentDataSubject,
+        signal: context_js_1.currentSignal,
+    };
+    const handles = new Map();
+    function lookup(target) {
+        if (typeof target === 'string') {
+            const found = declared.find((definition) => definition.alias.toLowerCase() === target.toLowerCase());
+            if (!found)
+                throw new Error(`Collection "${target}" is not declared in this data client's collections.`);
+            return found;
+        }
+        if (!declared.includes(target)) {
+            throw new Error(`Collection "${target.alias}" is declared but missing from the \`collections\` passed to createDataClient.`);
+        }
+        return target;
+    }
+    function collection(target) {
+        const definition = lookup(target);
+        let handle = handles.get(definition);
+        if (!handle) {
+            handle = new collection_js_1.Collection(definition, runtime);
+            handles.set(definition, handle);
+        }
+        return handle;
+    }
+    async function transact(steps, options = {}) {
+        (0, collection_js_1.assertAtomicBatch)('data.transact', steps.length);
+        // Steps resolve their collection IDs inside the recovered call, so a retry uses fresh IDs.
+        const result = await bootstrap.recover(() => sendTransaction(steps, options));
+        const results = (result.results ?? []).map(({ document, ...item }) => ({
+            ...item,
+            ...(document ? { document: (0, collection_js_1.toDoc)(document) } : {}),
+        }));
+        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 error_js_1.DataError({
+                message: `Transaction ${result.status}: ${failed.map((item) => `${item.opId} ${JSON.stringify(item.error)}`).join('; ') || 'no step committed'}`,
+                status: execution === 'unknown' ? 503 : 409,
+                code: 'TRANSACTION_FAILED',
+                execution,
+                attempts: 1,
+                details: { status: result.status, results },
+            });
+        }
+        return { status: result.status, results };
+    }
+    async function sendTransaction(steps, options) {
+        const items = await Promise.all(steps.map(async ({ collection: target, sort, query, ...step }) => {
+            const definition = lookup(target);
+            const item = { ...step, collectionId: await bootstrap.resolve(definition) };
+            if (sort)
+                item.sort = (0, sort_js_1.toSortPairs)(sort);
+            if (query)
+                item.query = { ...query, ...(query.sort ? { sort: (0, sort_js_1.toSortPairs)(query.sort) } : {}) };
+            if (step.data) {
+                // Fields bound to earlier results are filled by UNS at commit; everything literal validates now.
+                const bound = (step.bindings ?? []).flatMap((binding) => (binding.path.startsWith('data.') ? [binding.path.slice(5).split('.')[0]] : []));
+                item.data = (0, schema_js_1.validateStepData)(definition, step.data, bound);
+            }
+            if (step.update)
+                item.update = (0, schema_js_1.validateUpdate)(definition, step.update);
+            return item;
+        }));
+        return call('recordTransactionExecute', {
+            items,
+            mode: 'sync',
+            ...(options.dryRun ? { dryRun: true } : {}),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }, { dataSubject: (0, context_js_1.currentDataSubject)(), signal: (0, context_js_1.currentSignal)() });
+    }
+    async function queryBatch(queries, options = {}) {
+        const names = Object.keys(queries);
+        if (names.length < 1 || names.length > exports.MAX_BATCH_QUERIES) {
+            throw new TypeError(`data.queryBatch takes 1–${exports.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: (0, context_js_1.currentDataSubject)(), signal: (0, context_js_1.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 = (0, subscribe_js_1.createSubscribe)({
+        openStream,
+        ensure: bootstrap.ensure,
+        rebuild: bootstrap.rebuild,
+        lookup,
+        declared,
+        subject: context_js_1.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 = (0, client_js_1.parseUnsV2Fault)(value);
+    if (!fault) {
+        return new error_js_1.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 client_js_1.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 (0, error_js_1.toDataError)(error);
+}
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +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 { 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/cjs/data/collection.d.ts

@@ -0,0 +1,335 @@
+import type { DataCall } from './call.js';
+import type { CollectionDefinition, RecordMeta } from './define.js';
+import { type Filter, type Sort, type SortPairs } from './sort.js';
+/** UNS page limit for find / aggregate / distinct. */
+export declare const MAX_PAGE_SIZE = 200;
+/**
+ * UNS commits at most 200 items in one synchronous atomic batch
+ * (insertMany, bulkWrite, data.transact).
+ */
+export declare const MAX_ATOMIC_ITEMS = 200;
+export type WithMeta<T> = T & {
+    _id: string;
+    _meta: RecordMeta;
+};
+export type Projection = Record<string, 0 | 1 | boolean>;
+export type Update = Record<string, unknown>;
+export interface UnsRecord {
+    id: string;
+    data: Record<string, unknown>;
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Position of the next page: an opaque cursor or a 1-based offset page number. */
+type PageToken = string | number;
+interface Page<T> {
+    items: T[];
+    /** Token of the following page; null when this was the last one. */
+    next: PageToken | null;
+}
+/** Runtime services a collection handle needs from its client. */
+export interface CollectionRuntime {
+    call: DataCall;
+    /** Collection ID of a declaration or declared alias, ensuring all declarations first. */
+    resolve(target: CollectionDefinition | string): Promise<string>;
+    /** Runs a call, re-ensuring and retrying once when its collection ID went stale (see bootstrap). */
+    recover<R>(fn: () => Promise<R>, options?: {
+        retry?: boolean;
+    }): 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;
+export declare function toDoc<T>(record: UnsRecord): WithMeta<T>;
+/**
+ * Async-iterable result set. Pages hold at most 200 items; the page source
+ * decides whether the next page is reached by cursor or by offset page number.
+ */
+export declare class Cursor<T> implements AsyncIterable<T> {
+    private readonly fetchPage;
+    private sortSpec?;
+    private limitCount?;
+    private projection?;
+    private started;
+    constructor(fetchPage: (state: {
+        token: PageToken | null;
+        size: number;
+        sort?: SortPairs;
+        projection?: Projection;
+    }) => Promise<Page<T>>, options?: {
+        sort?: Sort;
+        limit?: number;
+        projection?: Projection;
+    });
+    private assertNotStarted;
+    sort(sort: Sort): this;
+    /** Total number of documents to return (pages are fetched ≤200 at a time). */
+    limit(count: number): this;
+    project(projection: Projection): this;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    toArray(): Promise<T[]>;
+}
+export interface FindOptions {
+    sort?: Sort;
+    limit?: number;
+    projection?: Projection;
+}
+export interface FindPageOptions {
+    sort?: Sort;
+    /** 1-based page number. */
+    page?: number;
+    /** 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;
+    /** Reject the write with VERSION_CONFLICT unless the record is at this revision. */
+    expectedRevision?: number;
+    sort?: Sort;
+    arrayFilters?: Record<string, unknown>[];
+    idempotencyKey?: string;
+}
+export interface FindOneAndOptions extends UpdateOptions {
+    returnDocument?: 'before' | 'after';
+    projection?: Projection;
+}
+export type BulkOperation = {
+    insertOne: {
+        document: Record<string, unknown>;
+    };
+} | {
+    updateOne: {
+        filter: Filter;
+        update: Update;
+        upsert?: boolean;
+        sort?: Sort;
+    };
+} | {
+    replaceOne: {
+        filter: Filter;
+        replacement: Record<string, unknown>;
+        upsert?: boolean;
+        sort?: Sort;
+    };
+} | {
+    deleteOne: {
+        filter: Filter;
+        sort?: Sort;
+    };
+};
+export declare class Collection<T extends object = Record<string, unknown>, TInput extends object = T> {
+    readonly definition: CollectionDefinition;
+    private readonly runtime;
+    constructor(definition: CollectionDefinition, runtime: CollectionRuntime);
+    get alias(): string;
+    /**
+     * One call with stale-ID recovery. A call continuing a cursor or
+     * resumeAfter token of the old collection is not retried: the token means
+     * nothing to a recreated collection.
+     */
+    private post;
+    private send;
+    find(filter?: Filter, options?: FindOptions): Cursor<WithMeta<T>>;
+    findOne(filter?: Filter, options?: Omit<FindOptions, 'limit'>): Promise<WithMeta<T> | null>;
+    /**
+     * 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).
+     */
+    get(ids: readonly string[], options?: {
+        projection?: Projection;
+    }): Promise<{
+        items: WithMeta<T>[];
+        missing: string[];
+    }>;
+    /**
+     * 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[]>;
+    /**
+     * Runs a pipeline (`$match`, `$sort`, `$group`, `$project`, `$set`,
+     * `$lookup`, `$unwind`, `$skip`, `$limit`, `$count`). `$sort` accepts
+     * `{ field: 1 | -1 }`; `$lookup` takes `from` (a declared collection or
+     * alias of this App) instead of a collection ID. Rows are whatever the
+     * pipeline outputs, not wrapped records.
+     *
+     * Pipelines of only `$match` / `$sort` page by cursor; any other stage pages
+     * by offset (UNS rejects cursors for transformed results). The `$exists`,
+     * `$distinct` and `$frequencies` stages are listed in the UNS schema but not
+     * executed by the record pipeline; use `countDocuments`, `distinct` or `$group`.
+     */
+    aggregate<R = Record<string, unknown>>(pipeline: Record<string, unknown>[]): Cursor<R>;
+    private aggregatePage;
+    /** Converts Mongo-style `$sort` objects and resolves `$lookup.from`, recursively. */
+    private prepareStages;
+    insertOne(document: TInput & {
+        _id?: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        insertedId: string;
+    }>;
+    /** Inserts up to 200 documents atomically (all or none). */
+    insertMany(documents: readonly (TInput & {
+        _id?: string;
+    })[], options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        insertedCount: number;
+        insertedIds: string[];
+    }>;
+    updateOne(filter: Filter, update: Update, options?: UpdateOptions): Promise<{
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedId: string | null;
+    }>;
+    /**
+     * Updates every match like Mongo's updateMany: documents commit one by one
+     * (not atomically), following `resumeAfter` until every match is processed.
+     * 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'> & {
+        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`.
+     */
+    replaceOne(filter: Filter, replacement: TInput, options?: Omit<UpdateOptions, 'arrayFilters'>): Promise<{
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedId: string | null;
+    }>;
+    /** Soft-deletes one record; requires `uns.delete` on the App key. */
+    deleteOne(filter: Filter, options?: Pick<UpdateOptions, 'expectedRevision' | 'sort' | 'idempotencyKey'>): Promise<{
+        deletedCount: number;
+    }>;
+    /**
+     * Soft-deletes every match, one document at a time like Mongo's deleteMany
+     * (not atomic), following `resumeAfter`; requires `uns.delete` on the App
+     * key. Failures after committed deletes report them as updateMany does.
+     */
+    deleteMany(filter: Filter, options?: {
+        resumeAfter?: string;
+    }): Promise<{
+        deletedCount: number;
+    }>;
+    /**
+     * Atomic read-modify-write. A state transition puts the expected state in
+     * the filter: `findOneAndUpdate({ _id, status: "DRAFT" }, { $set: { status: "SUBMITTED" } })`
+     * returns null when another request moved the record first.
+     */
+    findOneAndUpdate(filter: Filter, update: Update, options?: FindOneAndOptions): Promise<WithMeta<T> | null>;
+    findOneAndReplace(filter: Filter, replacement: TInput, options?: Omit<FindOneAndOptions, 'arrayFilters'>): Promise<WithMeta<T> | null>;
+    findOneAndDelete(filter: Filter, options?: Pick<FindOneAndOptions, 'expectedRevision' | 'sort' | 'projection' | 'idempotencyKey'>): Promise<WithMeta<T> | null>;
+    /** Up to 200 mixed single-record writes in one atomic call (insertOne / updateOne / replaceOne / deleteOne). */
+    bulkWrite(operations: readonly BulkOperation[], options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        insertedCount: number;
+        matchedCount: number;
+        modifiedCount: number;
+        deletedCount: number;
+        upsertedCount: number;
+        insertedIds: Record<number, string>;
+        upsertedIds: Record<number, string>;
+    }>;
+}
+export {};