@tier0/sdk-v2 0.0.0-stage → 0.1.0

package/dist/cjs/data/call.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DATA_TIMEOUT_MS = void 0;
+exports.createDataCall = createDataCall;
+/**
+ * One UNS call of the data layer. The SDK's UNS client resolves host and key,
+ * sends the request and checks the envelope; this binds the employee data
+ * subject of the current call and turns every failure into a `DataError`.
+ */
+const client_js_1 = require("../openapi/client.js");
+const client_js_2 = require("../uns-v2/client.js");
+const error_js_1 = require("./error.js");
+/** UNS statements time out at 15 s, so a data call waits no longer by default. */
+exports.DEFAULT_DATA_TIMEOUT_MS = 15_000;
+function createDataCall(config) {
+    const http = new client_js_1.HttpClient(config);
+    const resolve = () => http;
+    const transport = { transportTimeoutMs: config.transportTimeoutMs ?? exports.DEFAULT_DATA_TIMEOUT_MS };
+    const app = new client_js_2.UnsV2ClientCore(resolve, transport);
+    function assertConfigured() {
+        let problem;
+        try {
+            http.getBaseURL();
+            if (!http.getApiKey()?.trim())
+                problem = 'TIER0_API_KEY is not set';
+        }
+        catch (error) {
+            problem = error instanceof Error ? error.message : String(error);
+        }
+        if (problem) {
+            throw new error_js_1.DataError({
+                message: `${problem}. The platform injects TIER0_API_HOST and TIER0_API_KEY in Preview and deployments; for local development set them before starting the App.`,
+                status: 503,
+                code: 'DATA_NOT_CONFIGURED',
+            });
+        }
+    }
+    return async function call(operation, request, options = {}) {
+        assertConfigured();
+        // The SDK binds a data subject to one client; App-level calls use the shared one without it.
+        const core = options.dataSubject ? new client_js_2.UnsV2ClientCore(resolve, { ...transport, unsV2AppDataSubject: options.dataSubject }) : app;
+        try {
+            const response = await core.call(operation, request);
+            return response.data;
+        }
+        catch (error) {
+            throw error instanceof client_js_2.UnsV2Error ? (0, error_js_1.toDataError)(error) : error;
+        }
+    };
+}
+//# sourceMappingURL=call.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"call.js","sourceRoot":"","sources":["../../../src/data/call.ts"],"names":[],"mappings":";;;AAqBA,wCAkCC;AAvDD;;;;GAIG;AACH,oDAAqE;AACrE,mDAAkE;AAElE,yCAAoD;AAEpD,kFAAkF;AACrE,QAAA,uBAAuB,GAAG,MAAM,CAAC;AAU9C,SAAgB,cAAc,CAAC,MAAoB;IACjD,MAAM,IAAI,GAAG,IAAI,sBAAU,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC;IAC3B,MAAM,SAAS,GAAG,EAAE,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,IAAI,+BAAuB,EAAE,CAAC;IAC/F,MAAM,GAAG,GAAG,IAAI,2BAAe,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAEpD,SAAS,gBAAgB;QACvB,IAAI,OAA2B,CAAC;QAChC,IAAI,CAAC;YACH,IAAI,CAAC,UAAU,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE;gBAAE,OAAO,GAAG,0BAA0B,CAAC;QACtE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,IAAI,oBAAS,CAAC;gBAClB,OAAO,EAAE,GAAG,OAAO,6IAA6I;gBAChK,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,qBAAqB;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,UAAU,IAAI,CAAI,SAA6B,EAAE,OAAgC,EAAE,UAAuB,EAAE;QACtH,gBAAgB,EAAE,CAAC;QACnB,6FAA6F;QAC7F,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,2BAAe,CAAC,OAAO,EAAE,EAAE,GAAG,SAAS,EAAE,mBAAmB,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAClI,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAyC,CAAC,CAAC;YACvF,OAAO,QAAQ,CAAC,IAAS,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,YAAY,sBAAU,CAAC,CAAC,CAAC,IAAA,sBAAW,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACjE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * One UNS call of the data layer. The SDK's UNS client resolves host and key,\n * sends the request and checks the envelope; this binds the employee data\n * subject of the current call and turns every failure into a `DataError`.\n */\nimport { HttpClient, type ClientConfig } from '../openapi/client.js';\nimport { UnsV2ClientCore, UnsV2Error } from '../uns-v2/client.js';\nimport type { UnsV2OperationName, UnsV2Request } from '../uns-v2/generated.js';\nimport { DataError, toDataError } from './error.js';\n\n/** UNS statements time out at 15 s, so a data call waits no longer by default. */\nexport const DEFAULT_DATA_TIMEOUT_MS = 15_000;\n\nexport interface CallOptions {\n  /** Employee assertion forwarded from the current business request. */\n  dataSubject?: string;\n}\n\n/** Sends one operation and resolves with the envelope's `data`. */\nexport type DataCall = <T>(operation: UnsV2OperationName, request: Record<string, unknown>, options?: CallOptions) => Promise<T>;\n\nexport function createDataCall(config: ClientConfig): DataCall {\n  const http = new HttpClient(config);\n  const resolve = () => http;\n  const transport = { transportTimeoutMs: config.transportTimeoutMs ?? DEFAULT_DATA_TIMEOUT_MS };\n  const app = new UnsV2ClientCore(resolve, transport);\n\n  function assertConfigured() {\n    let problem: string | undefined;\n    try {\n      http.getBaseURL();\n      if (!http.getApiKey()?.trim()) problem = 'TIER0_API_KEY is not set';\n    } catch (error) {\n      problem = error instanceof Error ? error.message : String(error);\n    }\n    if (problem) {\n      throw new DataError({\n        message: `${problem}. The platform injects TIER0_API_HOST and TIER0_API_KEY in Preview and deployments; for local development set them before starting the App.`,\n        status: 503,\n        code: 'DATA_NOT_CONFIGURED',\n      });\n    }\n  }\n\n  return async function call<T>(operation: UnsV2OperationName, request: Record<string, unknown>, options: CallOptions = {}): Promise<T> {\n    assertConfigured();\n    // The SDK binds a data subject to one client; App-level calls use the shared one without it.\n    const core = options.dataSubject ? new UnsV2ClientCore(resolve, { ...transport, unsV2AppDataSubject: options.dataSubject }) : app;\n    try {\n      const response = await core.call(operation, request as UnsV2Request<typeof operation>);\n      return response.data as T;\n    } catch (error) {\n      throw error instanceof UnsV2Error ? toDataError(error) : error;\n    }\n  };\n}\n"]}

package/dist/cjs/data/client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Data client factory: collection handles, cross-collection transactions and
+ * the shared bootstrap. An App builds one client per process from its
+ * collection declarations; tests build their own with a mock `fetch`.
+ */
+import type { z } from 'zod';
+import type { ClientConfig } from '../openapi/client.js';
+import { type DataEnvironment, type EnsureState, type Logger } from './bootstrap.js';
+import { Collection, type WithMeta } from './collection.js';
+import { type CollectionDefinition } from './define.js';
+import { type Filter, type Sort } from './sort.js';
+export type TransactAction = 'record.create' | 'record.check' | 'record.read' | 'record.update' | 'record.modify' | 'record.replace' | 'record.delete' | 'record.query';
+/** One `recordTransactionExecute` item; `collection` is a declaration or alias instead of a collection ID. */
+export interface TransactStep {
+    opId: string;
+    action: TransactAction;
+    collection: CollectionDefinition | string;
+    id?: string | {
+        ref: string;
+    };
+    filter?: Filter;
+    data?: Record<string, unknown>;
+    update?: Record<string, unknown>;
+    upsert?: boolean;
+    expectedRevision?: number;
+    dependsOn?: string[];
+    bindings?: {
+        path: string;
+        ref: string;
+        resultPath: string;
+    }[];
+    selection?: 'exactOne' | 'first';
+    sort?: Sort;
+    returnDocument?: 'before' | 'after';
+    exists?: boolean;
+    operations?: Record<string, unknown>[];
+    conditions?: Filter[];
+    /** `record.query`: rows to bind from; `expectCount` asserts the match count before `limit`. */
+    query?: {
+        filter?: Filter;
+        sort?: Sort;
+        limit?: number;
+        expectCount?: {
+            min?: number;
+            max?: number;
+        };
+    };
+    arrayFilters?: Record<string, unknown>[];
+}
+export interface TransactResultItem {
+    opId: string;
+    action: string;
+    id: string;
+    status: string;
+    collectionId?: string;
+    revision?: number;
+    /** Before/after snapshot when requested, as a flat document. */
+    document?: WithMeta<Record<string, unknown>>;
+    data?: unknown;
+    query?: unknown;
+    error?: unknown;
+}
+export interface TransactResult {
+    status: string;
+    results: TransactResultItem[];
+}
+/** Credentials as for `createClient`; `transportTimeoutMs` defaults to 15 s here, the UNS statement timeout. */
+export interface DataClientConfig extends ClientConfig {
+    collections: readonly CollectionDefinition[];
+    /** Defaults to "deployed" when NODE_ENV is production, otherwise "preview". */
+    environment?: DataEnvironment;
+    logger?: Logger;
+}
+export interface DataClient {
+    /** Typed handle for a declaration listed in `collections`. */
+    collection<C extends CollectionDefinition>(definition: C): Collection<z.output<C['schema']>, z.input<C['schema']>>;
+    /** Handle by alias, typed by the caller. */
+    collection<T extends object = Record<string, unknown>>(alias: string): Collection<T>;
+    /**
+     * Atomic multi-record, multi-collection write (`recordTransactionExecute`, sync),
+     * at most 200 steps. Steps can depend on each other (`dependsOn`) and bind
+     * earlier results (`bindings`). This is not a Mongo session: everything is
+     * sent at once.
+     */
+    transact(steps: readonly TransactStep[], options?: {
+        dryRun?: boolean;
+        idempotencyKey?: string;
+    }): Promise<TransactResult>;
+    /** Ensures every declaration now (normally lazy on first access). */
+    ensure(): Promise<EnsureState>;
+}
+export declare function createDataClient(config: DataClientConfig): DataClient;

package/dist/cjs/data/client.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 error_js_1 = require("./error.js");
+const schema_js_1 = require("./schema.js");
+const sort_js_1 = require("./sort.js");
+function createDataClient(config) {
+    const call = (0, call_js_1.createDataCall)(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,
+    };
+    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);
+            throw new error_js_1.DataError({
+                message: `Transaction ${result.status}: ${failed.map((item) => `${item.opId} ${JSON.stringify(item.error)}`).join('; ') || 'no step committed'}`,
+                status: 409,
+                code: 'TRANSACTION_FAILED',
+                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)() });
+    }
+    return { collection: collection, transact, ensure: bootstrap.ensure };
+}
+//# 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 { 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"]}

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

@@ -0,0 +1,238 @@
+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;
+}
+/** 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;
+}
+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>;
+    /**
+     * One numbered page plus the total match count, for paged list screens.
+     * Uses `recordAggregatePipeline` offset paging.
+     */
+    findPage(filter?: Filter, options?: FindPageOptions): Promise<{
+        items: WithMeta<T>[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    countDocuments(filter?: Filter): Promise<number>;
+    /** 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 stops the run and reports the counts already committed. For
+     * all-or-nothing multi-document changes use `data.transact` (≤200 items).
+     */
+    updateMany(filter: Filter, update: Update, options?: Pick<UpdateOptions, 'arrayFilters'>): Promise<{
+        matchedCount: number;
+        modifiedCount: number;
+    }>;
+    /**
+     * 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.
+     */
+    deleteMany(filter: Filter): 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 {};