@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/dist/esm/data/collection.js

@@ -0,0 +1,594 @@
+import { DataError } from './error.js';
+import { validateDocument, validateUpdate } from './schema.js';
+import { toSortPairs } from './sort.js';
+/** UNS page limit for find / aggregate / distinct. */
+export const MAX_PAGE_SIZE = 200;
+/**
+ * UNS commits at most 200 items in one synchronous atomic batch
+ * (insertMany, bulkWrite, data.transact).
+ */
+export const MAX_ATOMIC_ITEMS = 200;
+/** Rejects batches UNS would refuse, before anything is sent. */
+export function assertAtomicBatch(operation, count) {
+    if (count > MAX_ATOMIC_ITEMS) {
+        throw new DataError({
+            message: `${operation} commits at most ${MAX_ATOMIC_ITEMS} items atomically; got ${count}. ` +
+                `Split the input into chunks of ${MAX_ATOMIC_ITEMS} (each chunk commits on its own; give each chunk a stable ` +
+                'idempotencyKey or fixed _ids so a retry is safe), or keep all-or-nothing work within one batch.',
+            status: 400,
+            code: 'BATCH_LIMIT_EXCEEDED',
+        });
+    }
+}
+export function toDoc(record) {
+    return {
+        ...record.data,
+        _id: record.id,
+        _meta: { revision: record.revision, createdAt: record.createdAt, updatedAt: record.updatedAt },
+    };
+}
+/**
+ * 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 class Cursor {
+    fetchPage;
+    sortSpec;
+    limitCount;
+    projection;
+    started = false;
+    constructor(fetchPage, options = {}) {
+        this.fetchPage = fetchPage;
+        this.sortSpec = options.sort;
+        this.limitCount = options.limit;
+        this.projection = options.projection;
+    }
+    assertNotStarted() {
+        if (this.started)
+            throw new Error('Cursor options must be set before iteration starts.');
+    }
+    sort(sort) {
+        this.assertNotStarted();
+        this.sortSpec = sort;
+        return this;
+    }
+    /** Total number of documents to return (pages are fetched ≤200 at a time). */
+    limit(count) {
+        this.assertNotStarted();
+        this.limitCount = count;
+        return this;
+    }
+    project(projection) {
+        this.assertNotStarted();
+        this.projection = projection;
+        return this;
+    }
+    async *[Symbol.asyncIterator]() {
+        this.started = true;
+        const sort = toSortPairs(this.sortSpec);
+        let remaining = this.limitCount ?? Number.POSITIVE_INFINITY;
+        // One page size for the whole iteration: offset pages are only stable when it never changes.
+        const size = Math.min(MAX_PAGE_SIZE, remaining);
+        let token = null;
+        while (remaining > 0) {
+            const page = await this.fetchPage({ token, size, sort, projection: this.projection });
+            for (const item of page.items.slice(0, remaining))
+                yield item;
+            remaining -= page.items.length;
+            if (page.next === null || page.items.length === 0)
+                return;
+            token = page.next;
+        }
+    }
+    async toArray() {
+        const out = [];
+        for await (const item of this)
+            out.push(item);
+        return out;
+    }
+}
+/** Pipelines made only of `$match` / `$sort` page by cursor; UNS requires offset paging for any other stage. */
+function isDirectPipeline(stages) {
+    return stages.every((stage) => Object.keys(stage).every((key) => key === '$match' || key === '$sort'));
+}
+/** UNS reads at most 100 records by ID per request. */
+export const MAX_GET_IDS = 100;
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function filterOrNothing(filter) {
+    return Object.keys(filter).length > 0 ? filter : undefined;
+}
+/** `recordAggregatePipeline` body of one numbered page with its capped total. */
+function pageRequest(filter, options) {
+    const page = Math.max(1, Math.trunc(options.page ?? 1));
+    const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, Math.trunc(options.pageSize ?? 20)));
+    const pipeline = [];
+    if (Object.keys(filter).length > 0)
+        pipeline.push({ $match: filter });
+    const sort = toSortPairs(options.sort);
+    if (sort)
+        pipeline.push({ $sort: sort });
+    if (options.projection)
+        pipeline.push({ $project: options.projection });
+    const body = { pipeline, page: { mode: 'offset', page, size: pageSize }, count: options.maxCount === undefined ? {} : { max: options.maxCount } };
+    return { body, page, pageSize };
+}
+function countByPipeline(field, filter) {
+    const pipeline = [];
+    if (Object.keys(filter).length > 0)
+        pipeline.push({ $match: filter });
+    // `_id` breaks ties, so offset pages of equal counts neither repeat nor skip a group.
+    pipeline.push({ $group: { _id: `$${field}`, count: { $sum: 1 } } }, { $sort: { count: -1, _id: 1 } });
+    return pipeline;
+}
+const toValueCount = (row) => ({ value: row._id ?? null, count: row.count });
+function idsInOrder(ids) {
+    return Object.entries(ids ?? {})
+        .sort(([a], [b]) => Number(a) - Number(b))
+        .map(([, id]) => id);
+}
+/**
+ * Atomic batches pass no `committed` counts: their write errors rolled the
+ * whole batch back. Non-atomic runs pass their cumulative counts; `details`
+ * then has the shape `partialWrite` uses.
+ */
+function assertNoWriteErrors(result, operation, committed) {
+    if (result.writeErrors && result.writeErrors.length > 0) {
+        const counts = Object.entries(committed ?? {}).map(([name, value]) => `${name}=${value}`).join(', ');
+        const changed = committed !== undefined && Object.values(committed).some((value) => value > 0);
+        throw new DataError({
+            message: `${operation} stopped on ${result.writeErrors.length} write error(s)${counts ? `; already committed: ${counts}` : ''}.`,
+            status: 409,
+            code: 'WRITE_ERRORS',
+            execution: changed ? 'committed' : 'rolledBack',
+            attempts: 1,
+            details: committed
+                ? { ...committed, status: changed ? 'partiallyCommitted' : 'failed', hasMore: Boolean(result.hasMore), resumeAfter: result.resumeAfter ?? null, writeErrors: result.writeErrors }
+                : { writeErrors: result.writeErrors },
+        });
+    }
+}
+/**
+ * A non-atomic run failed after some writes committed: on an earlier page, or
+ * within the failed page (UNS then answers `execution: "committed"` with the
+ * page's partial result as `data`). Like UNS, the error keeps its code and is
+ * `committed` with `retry.safe: false`; `details` is the cumulative result
+ * of the whole call in the shape of a success (`matchedCount` …, `status:
+ * "partiallyCommitted"`, `hasMore`, `resumeAfter`). Continue by passing
+ * `resumeAfter` back; repeating the call would apply `$inc` / `$push` twice.
+ */
+function partialWrite(operation, totals, resumeAfter, cause) {
+    const counts = Object.entries(totals).map(([name, value]) => `${name}=${value}`).join(', ');
+    const writeErrors = Array.isArray(cause.details.writeErrors) ? { writeErrors: cause.details.writeErrors } : {};
+    return new DataError({
+        message: `${operation} committed ${counts} and then failed: ${cause.message} ` +
+            (resumeAfter
+                ? `Continue with { resumeAfter: details.resumeAfter }${cause.outcomeUnknown ? ' after checking the failed page, whose outcome is unknown' : ''}; do not repeat the whole call.`
+                : 'Read back what changed before writing again; do not repeat the whole call.'),
+        status: cause.status,
+        code: cause.code,
+        reason: cause.reason,
+        upstreamStatus: cause.upstreamStatus,
+        requestId: cause.requestId,
+        // Earlier writes took effect; the failed page too, perhaps, when its outcome is unknown.
+        execution: cause.outcomeUnknown ? 'unknown' : 'committed',
+        retry: { safe: false },
+        attempts: cause.attempts,
+        details: { ...totals, status: 'partiallyCommitted', hasMore: true, resumeAfter: resumeAfter ?? null, ...writeErrors },
+        cause,
+    });
+}
+export class Collection {
+    definition;
+    runtime;
+    constructor(definition, runtime) {
+        this.definition = definition;
+        this.runtime = runtime;
+    }
+    get alias() {
+        return this.definition.alias;
+    }
+    /**
+     * 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.
+     */
+    post(operation, body, options = {}) {
+        const page = body.page;
+        const continues = typeof body.cursor === 'string' || typeof body.resumeAfter === 'string' || typeof page?.cursor === 'string';
+        return this.runtime.recover(() => this.send(operation, body, options), { retry: !continues });
+    }
+    async send(operation, body, options = {}) {
+        const collectionId = await this.runtime.resolve(this.definition);
+        return this.runtime.call(operation, { collectionId, ...compact(body) }, {
+            dataSubject: this.runtime.subject(),
+            signal: this.runtime.signal(),
+            ...options,
+        });
+    }
+    /* ---------------------------------- reads --------------------------------- */
+    find(filter = {}, options = {}) {
+        return new Cursor(async ({ token, size, sort, projection }) => {
+            const result = await this.post('recordFind', {
+                filter: Object.keys(filter).length > 0 ? filter : undefined,
+                sort,
+                projection,
+                limit: size,
+                cursor: typeof token === 'string' ? token : undefined,
+            });
+            return {
+                items: result.items.map((record) => toDoc(record)),
+                next: result.pageInfo.hasMore && result.pageInfo.nextCursor ? result.pageInfo.nextCursor : null,
+            };
+        }, options);
+    }
+    async findOne(filter = {}, options = {}) {
+        const [first] = await this.find(filter, { ...options, limit: 1 }).toArray();
+        return first ?? 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).
+     */
+    async get(ids, options = {}) {
+        const unique = [...new Set(ids)];
+        const chunks = [];
+        for (let start = 0; start < unique.length; start += MAX_GET_IDS)
+            chunks.push(unique.slice(start, start + MAX_GET_IDS));
+        const results = await Promise.all(chunks.map((chunk) => this.post('recordGet', { ids: chunk, projection: options.projection })));
+        return {
+            items: results.flatMap((result) => result.items.map((record) => toDoc(record))),
+            missing: results.flatMap((result) => result.missing),
+        };
+    }
+    /**
+     * 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+".
+     */
+    async findPage(filter = {}, options = {}) {
+        const { body, page, pageSize } = pageRequest(filter, options);
+        const result = await this.post('recordAggregatePipeline', body);
+        return { items: result.items, total: result.total, page, pageSize };
+    }
+    /**
+     * Counts matches up to `maxCount` (1–100000, UNS default 100000). A
+     * `capped` result means "at least `count`".
+     */
+    async countDocuments(filter = {}, options = {}) {
+        const result = await this.post('recordCount', { filter: filterOrNothing(filter), maxCount: options.maxCount });
+        return { count: result.count, capped: result.capped };
+    }
+    /**
+     * 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`.
+     */
+    async countBy(field, filter = {}) {
+        const rows = await this.aggregate(countByPipeline(field, filter)).toArray();
+        return rows.map(toValueCount);
+    }
+    /**
+     * 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() {
+        const one = (op, build, parse) => ({
+            collection: this.definition,
+            prepare: async () => ({ op, ...compact(await build()) }),
+            parse: parse,
+        });
+        return {
+            find: (filter = {}, options = {}) => one('find', async () => ({
+                filter: filterOrNothing(filter),
+                sort: toSortPairs(options.sort),
+                projection: options.projection,
+                limit: Math.min(MAX_PAGE_SIZE, options.limit ?? 20),
+                count: options.maxCount === undefined ? undefined : { max: options.maxCount },
+            }), (data) => ({
+                items: data.items.map((record) => toDoc(record)),
+                hasMore: data.pageInfo.hasMore,
+                ...(data.total ? { total: data.total } : {}),
+            })),
+            findPage: (filter = {}, options = {}) => {
+                const { body, page, pageSize } = pageRequest(filter, options);
+                return one('aggregate', async () => body, (data) => ({
+                    items: data.items, total: data.total, page, pageSize,
+                }));
+            },
+            count: (filter = {}, options = {}) => one('count', async () => ({ filter: filterOrNothing(filter), maxCount: options.maxCount }), (data) => ({ count: data.count, capped: data.capped })),
+            countBy: (field, filter = {}) => one('aggregate', async () => ({
+                pipeline: await this.prepareStages(countByPipeline(field, filter)),
+                page: { mode: 'offset', page: 1, size: MAX_PAGE_SIZE },
+            }), (data) => data.items.map(toValueCount)),
+            distinct: (field, filter = {}) => one('distinct', async () => ({ field, filter: filterOrNothing(filter), page: { mode: 'offset', page: 1, size: MAX_PAGE_SIZE } }), (data) => data.values),
+            aggregate: (pipeline) => one('aggregate', async () => {
+                const stages = await this.prepareStages(pipeline);
+                const last = stages[stages.length - 1];
+                // A final $count returns one row and forbids an explicit page.
+                return last !== undefined && '$count' in last
+                    ? { pipeline: stages }
+                    : { pipeline: stages, page: isDirectPipeline(stages) ? { mode: 'cursor', size: MAX_PAGE_SIZE } : { mode: 'offset', page: 1, size: MAX_PAGE_SIZE } };
+            }, (data) => data.items),
+            get: (ids, options = {}) => {
+                const unique = [...new Set(ids)];
+                if (unique.length < 1 || unique.length > MAX_GET_IDS) {
+                    throw new TypeError(`query.get takes 1–${MAX_GET_IDS} distinct IDs; use collection.get for more.`);
+                }
+                return one('get', async () => ({ ids: unique, projection: options.projection }), (data) => ({ items: data.items.map((record) => toDoc(record)), missing: data.missing }));
+            },
+        };
+    }
+    /** Distinct values of a field (every page). */
+    async distinct(field, filter = {}) {
+        const values = [];
+        for (let page = 1;; page += 1) {
+            const result = await this.post('recordDistinct', {
+                field,
+                filter: Object.keys(filter).length > 0 ? filter : undefined,
+                page: { mode: 'offset', page, size: MAX_PAGE_SIZE },
+            });
+            values.push(...result.values);
+            if (!result.pageInfo.hasMore)
+                return values;
+        }
+    }
+    /**
+     * 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(pipeline) {
+        // Recovery wraps stage preparation too, so a retry re-resolves `$lookup` IDs.
+        return new Cursor(({ token, size }) => this.runtime.recover(() => this.aggregatePage(pipeline, token, size), { retry: typeof token !== 'string' }));
+    }
+    async aggregatePage(pipeline, token, size) {
+        const stages = await this.prepareStages(pipeline);
+        const last = stages[stages.length - 1];
+        if (last !== undefined && '$count' in last) {
+            // A final $count returns one row and forbids an explicit page.
+            const result = await this.send('recordAggregatePipeline', { pipeline: stages });
+            return { items: result.items, next: null };
+        }
+        if (isDirectPipeline(stages)) {
+            const result = await this.send('recordAggregatePipeline', {
+                pipeline: stages,
+                page: { mode: 'cursor', size, ...(typeof token === 'string' ? { cursor: token } : {}) },
+            });
+            return { items: result.items, next: result.pageInfo.hasMore && result.pageInfo.nextCursor ? result.pageInfo.nextCursor : null };
+        }
+        const page = typeof token === 'number' ? token : 1;
+        const result = await this.send('recordAggregatePipeline', {
+            pipeline: stages,
+            page: { mode: 'offset', page, size },
+        });
+        return {
+            items: result.items,
+            next: result.pageInfo.hasMore ? (result.pageInfo.nextPage ?? page + 1) : null,
+        };
+    }
+    /** Converts Mongo-style `$sort` objects and resolves `$lookup.from`, recursively. */
+    async prepareStages(pipeline) {
+        return Promise.all(pipeline.map(async (stage) => {
+            if ('$sort' in stage && !Array.isArray(stage.$sort)) {
+                return { ...stage, $sort: toSortPairs(stage.$sort) };
+            }
+            if ('$lookup' in stage && stage.$lookup && typeof stage.$lookup === 'object') {
+                const { from, pipeline: inner, ...lookup } = stage.$lookup;
+                const resolved = { ...lookup };
+                if (from !== undefined)
+                    resolved.collectionId = await this.runtime.resolve(from);
+                if (Array.isArray(inner))
+                    resolved.pipeline = await this.prepareStages(inner);
+                return { ...stage, $lookup: resolved };
+            }
+            return stage;
+        }));
+    }
+    /* --------------------------------- writes --------------------------------- */
+    async insertOne(document, options = {}) {
+        const { id, data } = validateDocument(this.definition, document);
+        const result = await this.post('recordInsertOne', { id, data, idempotencyKey: options.idempotencyKey });
+        return { insertedId: result.insertedId };
+    }
+    /** Inserts up to 200 documents atomically (all or none). */
+    async insertMany(documents, options = {}) {
+        if (documents.length === 0)
+            return { insertedCount: 0, insertedIds: [] };
+        assertAtomicBatch('insertMany', documents.length);
+        const prepared = documents.map((document) => validateDocument(this.definition, document));
+        const result = await this.post('recordInsertMany', {
+            documents: prepared.map(({ id, data }) => compact({ id, data })),
+            ordered: true,
+            atomic: true,
+            idempotencyKey: options.idempotencyKey,
+        });
+        assertNoWriteErrors(result, 'insertMany');
+        return { insertedCount: result.insertedCount ?? 0, insertedIds: idsInOrder(result.insertedIds) };
+    }
+    async updateOne(filter, update, options = {}) {
+        const result = await this.post('recordUpdateOne', {
+            filter,
+            update: validateUpdate(this.definition, update),
+            upsert: options.upsert,
+            expectedRevision: options.expectedRevision,
+            sort: toSortPairs(options.sort),
+            arrayFilters: options.arrayFilters,
+            idempotencyKey: options.idempotencyKey,
+        });
+        return { matchedCount: result.matchedCount ?? 0, modifiedCount: result.modifiedCount ?? 0, upsertedId: result.upsertedId ?? 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).
+     */
+    async updateMany(filter, update, options = {}) {
+        const validated = validateUpdate(this.definition, update);
+        let matchedCount = 0;
+        let modifiedCount = 0;
+        await this.writeEach('updateMany', 'recordUpdateMany', { filter, update: validated, arrayFilters: options.arrayFilters }, options.resumeAfter, (result) => {
+            matchedCount += result.matchedCount ?? 0;
+            modifiedCount += result.modifiedCount ?? 0;
+            return { matchedCount, modifiedCount };
+        });
+        return { matchedCount, modifiedCount };
+    }
+    /** Runs a non-atomic many-write page by page; see updateMany for failures. */
+    async writeEach(name, operation, body, from, add) {
+        let resumeAfter = from;
+        let committed;
+        do {
+            let result;
+            try {
+                result = await this.post(operation, { ...body, atomic: false, resumeAfter });
+            }
+            catch (error) {
+                if (!(error instanceof DataError))
+                    throw error;
+                // UNS reports what the failed page itself committed, with where to continue.
+                const page = error.execution === 'committed' ? error.details : undefined;
+                const totals = page ? add(page) : committed;
+                // Nothing of this call took effect: the page's own error tells the truth.
+                if (!totals || !Object.values(totals).some((value) => value > 0))
+                    throw error;
+                throw partialWrite(name, totals, page ? (page.resumeAfter ?? undefined) : resumeAfter, error);
+            }
+            committed = add(result);
+            assertNoWriteErrors(result, name, committed);
+            resumeAfter = result.hasMore && result.resumeAfter ? result.resumeAfter : undefined;
+        } while (resumeAfter);
+    }
+    /**
+     * Replaces the whole body. Fields written by another App version and not in
+     * this declaration are lost — prefer `updateOne` with `$set`.
+     */
+    async replaceOne(filter, replacement, options = {}) {
+        const { data } = validateDocument(this.definition, replacement);
+        const result = await this.post('recordReplaceOne', {
+            filter,
+            replacement: data,
+            upsert: options.upsert,
+            expectedRevision: options.expectedRevision,
+            sort: toSortPairs(options.sort),
+            idempotencyKey: options.idempotencyKey,
+        });
+        return { matchedCount: result.matchedCount ?? 0, modifiedCount: result.modifiedCount ?? 0, upsertedId: result.upsertedId ?? null };
+    }
+    /** Soft-deletes one record; requires `uns.delete` on the App key. */
+    async deleteOne(filter, options = {}) {
+        const result = await this.post('recordDeleteOne', { filter, expectedRevision: options.expectedRevision, sort: toSortPairs(options.sort), idempotencyKey: options.idempotencyKey });
+        return { deletedCount: result.deletedCount ?? 0 };
+    }
+    /**
+     * 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.
+     */
+    async deleteMany(filter, options = {}) {
+        let deletedCount = 0;
+        await this.writeEach('deleteMany', 'recordDeleteMany', { filter }, options.resumeAfter, (result) => {
+            deletedCount += result.deletedCount ?? 0;
+            return { deletedCount };
+        });
+        return { deletedCount };
+    }
+    /**
+     * 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.
+     */
+    async findOneAndUpdate(filter, update, options = {}) {
+        const result = await this.post('recordFindOneAndUpdate', {
+            filter,
+            update: validateUpdate(this.definition, update),
+            upsert: options.upsert,
+            expectedRevision: options.expectedRevision,
+            sort: toSortPairs(options.sort),
+            arrayFilters: options.arrayFilters,
+            returnDocument: options.returnDocument ?? 'after',
+            projection: options.projection,
+            idempotencyKey: options.idempotencyKey,
+        });
+        return result.value ? toDoc(result.value) : null;
+    }
+    async findOneAndReplace(filter, replacement, options = {}) {
+        const { data } = validateDocument(this.definition, replacement);
+        const result = await this.post('recordFindOneAndReplace', {
+            filter,
+            replacement: data,
+            upsert: options.upsert,
+            expectedRevision: options.expectedRevision,
+            sort: toSortPairs(options.sort),
+            returnDocument: options.returnDocument ?? 'after',
+            projection: options.projection,
+            idempotencyKey: options.idempotencyKey,
+        });
+        return result.value ? toDoc(result.value) : null;
+    }
+    async findOneAndDelete(filter, options = {}) {
+        const result = await this.post('recordFindOneAndDelete', {
+            filter,
+            expectedRevision: options.expectedRevision,
+            sort: toSortPairs(options.sort),
+            projection: options.projection,
+            idempotencyKey: options.idempotencyKey,
+        });
+        return result.value ? toDoc(result.value) : null;
+    }
+    /** Up to 200 mixed single-record writes in one atomic call (insertOne / updateOne / replaceOne / deleteOne). */
+    async bulkWrite(operations, options = {}) {
+        assertAtomicBatch('bulkWrite', operations.length);
+        const mapped = operations.map((operation) => {
+            if ('insertOne' in operation) {
+                const { id, data } = validateDocument(this.definition, operation.insertOne.document);
+                return { insertOne: compact({ id, data }) };
+            }
+            if ('updateOne' in operation) {
+                const { filter, update, upsert, sort } = operation.updateOne;
+                return { updateOne: compact({ filter, update: validateUpdate(this.definition, update), upsert, sort: toSortPairs(sort) }) };
+            }
+            if ('replaceOne' in operation) {
+                const { filter, replacement, upsert, sort } = operation.replaceOne;
+                const { data } = validateDocument(this.definition, replacement);
+                return { replaceOne: compact({ filter, replacement: data, upsert, sort: toSortPairs(sort) }) };
+            }
+            if ('deleteOne' in operation) {
+                return { deleteOne: compact({ filter: operation.deleteOne.filter, sort: toSortPairs(operation.deleteOne.sort) }) };
+            }
+            throw new Error(`Unsupported bulkWrite operation ${Object.keys(operation).join(', ')}; use updateMany() / deleteMany() or data.transact().`);
+        });
+        if (mapped.length === 0) {
+            return { insertedCount: 0, matchedCount: 0, modifiedCount: 0, deletedCount: 0, upsertedCount: 0, insertedIds: {}, upsertedIds: {} };
+        }
+        const result = await this.post('recordBulkWrite', { operations: mapped, ordered: true, atomic: true, idempotencyKey: options.idempotencyKey });
+        assertNoWriteErrors(result, 'bulkWrite');
+        const numericKeys = (ids) => Object.fromEntries(Object.entries(ids ?? {}).map(([index, id]) => [Number(index), id]));
+        return {
+            insertedCount: result.insertedCount ?? 0,
+            matchedCount: result.matchedCount ?? 0,
+            modifiedCount: result.modifiedCount ?? 0,
+            deletedCount: result.deletedCount ?? 0,
+            upsertedCount: result.upsertedCount ?? 0,
+            insertedIds: numericKeys(result.insertedIds),
+            upsertedIds: numericKeys(result.upsertedIds),
+        };
+    }
+}
+//# sourceMappingURL=collection.js.map