@fabriktor/fx 0.0.110 → 0.0.112

package/dist/src/billable/billable.d.ts

@@ -1,6 +1,7 @@
 import { type BillableOperator } from "@fabriktor/client";
 import { type Bill, BillableFolder, Charge, Equipment, Item, LaborRate, MeterReading, Quantifier, Tax, TmpBillNumber, VendorInvoice, Warehouse } from "@fabriktor/schema";
 import type { ContactsFXOperator, EmploymentOwnerScope } from "../contacts/contacts.js";
+import type { MultiCreateCheckpoint } from "../core/multi-create.js";
 import { type OwnerSearchOptions, type SearchOptions, type SearchPage, type SearchQuery } from "../core/search.js";
 type GenerateBillPayload = Parameters<BillableOperator["generateBill"]>[0];
 export type SalaryEstimateInput = GenerateBillPayload["salary_estimate"];
@@ -49,31 +50,31 @@ export type CreateBillableFolderOptions = BillableFolderInsertOptions;
 export type ReplaceBillableFolderOptions = BillableFolderReplaceOptions;
 export type SearchBillableFoldersOptions = OwnerSearchOptions;
 export type SearchBillableFoldersPage = SearchPage<BillableFolder>;
-export type CreateChargeOptions = ChargeInsertOptions;
+export type CreateChargeOptions = ChargeInsertOptions & MultiCreateCheckpoint;
 export type ReplaceChargeOptions = ChargeReplaceOptions;
 export type SearchChargesOptions = OwnerSearchOptions & ChargeSearchFields;
 export type SearchChargesPage = SearchPage<Charge>;
-export type CreateEquipmentOptions = EquipmentInsertOptions;
+export type CreateEquipmentOptions = EquipmentInsertOptions & MultiCreateCheckpoint;
 export type ReplaceEquipmentOptions = EquipmentReplaceOptions;
 export type SearchEquipmentsOptions = OwnerSearchOptions & EquipmentSearchFields;
 export type SearchEquipmentsPage = SearchPage<Equipment>;
-export type CreateItemOptions = ItemInsertOptions;
+export type CreateItemOptions = ItemInsertOptions & MultiCreateCheckpoint;
 export type ReplaceItemOptions = ItemReplaceOptions;
 export type SearchItemsOptions = OwnerSearchOptions & ItemSearchFields;
 export type SearchItemsPage = SearchPage<Item>;
-export type CreateLaborRateOptions = LaborRateInsertOptions;
+export type CreateLaborRateOptions = LaborRateInsertOptions & MultiCreateCheckpoint;
 export type ReplaceLaborRateOptions = LaborRateReplaceOptions;
 export type SearchLaborRatesOptions = OwnerSearchOptions & Partial<Pick<LaborRate, "is_archived">>;
 export type SearchLaborRatesPage = SearchPage<LaborRate>;
-export type CreateMeterReadingOptions = MeterReadingInsertOptions;
+export type CreateMeterReadingOptions = MeterReadingInsertOptions & MultiCreateCheckpoint;
 export type ReplaceMeterReadingOptions = MeterReadingReplaceOptions;
 export type SearchMeterReadingsOptions = OwnerSearchOptions & MeterReadingSearchFields;
 export type SearchMeterReadingsPage = SearchPage<MeterReading>;
-export type CreateQuantifierOptions = QuantifierInsertOptions;
+export type CreateQuantifierOptions = QuantifierInsertOptions & MultiCreateCheckpoint;
 export type ReplaceQuantifierOptions = QuantifierReplaceOptions;
 export type SearchQuantifiersOptions = OwnerSearchOptions & Partial<Pick<Quantifier, "is_archived">>;
 export type SearchQuantifiersPage = SearchPage<Quantifier>;
-export type CreateTaxOptions = TaxInsertOptions;
+export type CreateTaxOptions = TaxInsertOptions & MultiCreateCheckpoint;
 export type ReplaceTaxOptions = TaxReplaceOptions;
 export type SearchTaxesOptions = OwnerSearchOptions & Partial<Pick<Tax, "is_archived">>;
 export type SearchTaxesPage = SearchPage<Tax>;
@@ -82,14 +83,14 @@ export type CreateTmpBillNumberOptions = TmpBillNumberInsertOptions;
 export type ReplaceTmpBillNumberOptions = TmpBillNumberReplaceOptions;
 export type SearchTmpBillNumbersOptions = OwnerSearchOptions;
 export type SearchTmpBillNumbersPage = SearchPage<TmpBillNumber>;
-export type CreateVendorInvoiceOptions = VendorInvoiceInsertOptions & {
+export type CreateVendorInvoiceOptions = VendorInvoiceInsertOptions & MultiCreateCheckpoint & {
     owner_id: string;
     allow_duplicate?: boolean;
 };
 export type ReplaceVendorInvoiceOptions = VendorInvoiceReplaceOptions;
 export type SearchVendorInvoicesOptions = OwnerSearchOptions & Partial<Pick<VendorInvoice, "is_archived">>;
 export type SearchVendorInvoicesPage = SearchPage<VendorInvoice>;
-export type CreateWarehouseOptions = WarehouseInsertOptions;
+export type CreateWarehouseOptions = WarehouseInsertOptions & MultiCreateCheckpoint;
 export type ReplaceWarehouseOptions = WarehouseReplaceOptions;
 export type SearchWarehousesOptions = OwnerSearchOptions & Partial<Pick<Warehouse, "is_archived">>;
 export type SearchWarehousesPage = SearchPage<Warehouse>;

package/dist/src/billable/billable.js

@@ -155,8 +155,12 @@ export class BillableFX {
         });
     }
     async createCharge(opts) {
+        if (opts.created_id)
+            return await this.findCharge(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneCharge(opts);
         const id = requiredOperationID(out, msgCreatedChargeIDMissing);
+        opts.on_created?.(id);
         return await this.findCharge(id);
     }
     async replaceCharge(opts) {
@@ -184,8 +188,12 @@ export class BillableFX {
         });
     }
     async createEquipment(opts) {
+        if (opts.created_id)
+            return await this.findEquipment(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneEquipment(opts);
         const id = requiredOperationID(out, msgCreatedEquipmentIDMissing);
+        opts.on_created?.(id);
         return await this.findEquipment(id);
     }
     async replaceEquipment(opts) {
@@ -208,8 +216,12 @@ export class BillableFX {
         });
     }
     async createItem(opts) {
+        if (opts.created_id)
+            return await this.findItem(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneItem(opts);
         const id = requiredOperationID(out, msgCreatedItemIDMissing);
+        opts.on_created?.(id);
         return await this.findItem(id);
     }
     async replaceItem(opts) {
@@ -232,8 +244,12 @@ export class BillableFX {
         });
     }
     async createLaborRate(opts) {
+        if (opts.created_id)
+            return await this.findLaborRate(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneLaborRate(opts);
         const id = requiredOperationID(out, msgCreatedLaborRateIDMissing);
+        opts.on_created?.(id);
         return await this.findLaborRate(id);
     }
     async replaceLaborRate(opts) {
@@ -248,8 +264,12 @@ export class BillableFX {
         });
     }
     async createMeterReading(opts) {
+        if (opts.created_id)
+            return await this.findMeterReading(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneMeterReading(opts);
         const id = requiredOperationID(out, msgCreatedMeterReadingIDMissing);
+        opts.on_created?.(id);
         return await this.findMeterReading(id);
     }
     async replaceMeterReading(opts) {
@@ -276,8 +296,12 @@ export class BillableFX {
         });
     }
     async createQuantifier(opts) {
+        if (opts.created_id)
+            return await this.findQuantifier(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneQuantifier(opts);
         const id = requiredOperationID(out, msgCreatedQuantifierIDMissing);
+        opts.on_created?.(id);
         return await this.findQuantifier(id);
     }
     async replaceQuantifier(opts) {
@@ -302,8 +326,12 @@ export class BillableFX {
         });
     }
     async createTax(opts) {
+        if (opts.created_id)
+            return await this.findTax(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneTax(opts);
         const id = requiredOperationID(out, msgCreatedTaxIDMissing);
+        opts.on_created?.(id);
         return await this.findTax(id);
     }
     async replaceTax(opts) {
@@ -339,6 +367,8 @@ export class BillableFX {
         });
     }
     async createVendorInvoice(opts) {
+        if (opts.created_id)
+            return await this.findVendorInvoice(opts.created_id);
         const owner_id = opts.owner_id.trim();
         if (!owner_id) {
             throw errRequired({
@@ -353,8 +383,14 @@ export class BillableFX {
         if (!opts.allow_duplicate) {
             await this.checkVendorInvoiceNumber(owner_id, input.number);
         }
-        const out = await this.billable.insertOneVendorInvoice({ in: input });
+        opts.before_request?.();
+        const out = await this.billable.insertOneVendorInvoice({
+            in: input,
+            signal: opts.signal,
+            idempotency_key: opts.idempotency_key,
+        });
         const id = requiredOperationID(out, msgCreatedVendorInvoiceIDMissing);
+        opts.on_created?.(id);
         return await this.findVendorInvoice(id);
     }
     async replaceVendorInvoice(opts) {
@@ -369,8 +405,12 @@ export class BillableFX {
         });
     }
     async createWarehouse(opts) {
+        if (opts.created_id)
+            return await this.findWarehouse(opts.created_id);
+        opts.before_request?.();
         const out = await this.billable.insertOneWarehouse(opts);
         const id = requiredOperationID(out, msgCreatedWarehouseIDMissing);
+        opts.on_created?.(id);
         return await this.findWarehouse(id);
     }
     async replaceWarehouse(opts) {

package/dist/src/chat/send-queue.d.ts

@@ -46,6 +46,7 @@ export type ChatSendQueueOptions = {
     lock: ChatSendLock;
     upload: (entry: QueuedChat, signal: AbortSignal) => Promise<boolean>;
     changed?: (chat?: Chat) => void;
+    online?: () => boolean;
 };
 export declare class ChatSendQueue {
     private readonly opts;
@@ -97,4 +98,6 @@ export declare class ChatSendQueue {
     private publish;
 }
 export declare function chatSendNeedsRetry(entry: QueuedChat): boolean;
+export declare function chatSendCanRetry(entry: QueuedChat): boolean;
+export declare function chatSendCanRestore(entry: QueuedChat): boolean;
 export declare function chatSendCanRemove(entry: QueuedChat): boolean;

package/dist/src/chat/send-queue.js

@@ -16,8 +16,9 @@ export const ChatSendStatus = {
     Uploading: "uploading",
     UploadInterrupted: "upload_interrupted",
 };
-// Persistent creation FIFO per account and room. Creation never advances beyond
-// an uncertain head: it recovers automatically with its original request key.
+// Persistent creation FIFO per account and room. A creation is attempted once:
+// the backend rejects reused keys rather than replaying the original response.
+// Unconfirmed entries remain visible but never block later messages.
 // Retrieval, attachments, other rooms and other users are independent.
 export class ChatSendQueue {
     opts;
@@ -156,6 +157,11 @@ export class ChatSendQueue {
         }
         this.remember(chat);
         this.publish();
+        for (const entry of this.entries) {
+            if (!entry.chat && entry.server_id === chat.id) {
+                this.startConfirmation(entry, this.owner, this.controller.signal);
+            }
+        }
     }
     async refresh() {
         if (!this.enabled) {
@@ -184,12 +190,13 @@ export class ChatSendQueue {
             if (stored.length === 0 && this.pendingSaves.size === 0)
                 this.wakeup.cancel();
             for (const room of new Set(stored
-                .filter((entry) => !entry.chat && !entry.server_id)
+                .filter(chatSendCanCreate)
                 .map((entry) => entry.input.chat_room_id))) {
                 this.work(room, owner, signal);
             }
             for (const entry of stored) {
-                if (chatSendCanConfirm(entry)) {
+                if (chatSendCanConfirm(entry) ||
+                    (!entry.chat && entry.server_id && this.confirmed.has(entry.server_id))) {
                     this.startConfirmation(entry, owner, signal);
                 }
                 if (entry.chat && entry.status === ChatSendStatus.Uploading) {
@@ -207,7 +214,7 @@ export class ChatSendQueue {
     }
     async retry(id) {
         const entry = this.entries.find((value) => value.id === id);
-        if (!entry || !this.enabled) {
+        if (!entry || !this.enabled || !chatSendCanRetry(entry)) {
             return;
         }
         if (entry.sequence === undefined) {
@@ -233,7 +240,7 @@ export class ChatSendQueue {
                 return;
             }
             const current = (await this.opts.store.list(owner)).find((value) => value.id === id);
-            if (!current || !chatSendNeedsRetry(current)) {
+            if (!current || !chatSendCanRetry(current)) {
                 return;
             }
             if (current.chat) {
@@ -308,7 +315,7 @@ export class ChatSendQueue {
             owner_id: owner,
             scope: `chat-send:${room}`,
             signal,
-            select: (entry) => entry.input.chat_room_id === room && !entry.chat && !entry.server_id,
+            select: (entry) => entry.input.chat_room_id === room && chatSendCanCreate(entry),
             on_error: (err) => {
                 if (this.current(owner, signal)) {
                     this.error = err;
@@ -325,13 +332,23 @@ export class ChatSendQueue {
                 if (!this.current(owner, signal) || this.cancellations.has(entry.id)) {
                     return false;
                 }
-                // A persisted Sending marker is an interrupted request once we own
-                // the room lock. Reuse its key; never skip an unknown creation outcome.
+                // The room lock excludes a sender in another tab. A leftover attempt
+                // (including legacy automatic retries) has an unknown outcome, not
+                // permission to POST again with an already consumed key.
                 let current = this.pendingCreates.get(entry.id) ?? entry;
-                if (this.waitForRetry(current))
+                if (current.attempted && !current.server_id) {
+                    await this.save({
+                        ...current,
+                        status: ChatSendStatus.Failed,
+                        retry: undefined,
+                    });
+                    return true;
+                }
+                if (this.opts.online?.() === false)
                     return false;
                 const request = new AbortController();
                 const requestSignal = AbortSignal.any([signal, request.signal]);
+                let requestStarted = false;
                 this.sends.set(entry.id, request);
                 try {
                     if (!current.server_id) {
@@ -344,6 +361,7 @@ export class ChatSendQueue {
                         if (!this.current(owner, signal))
                             return false;
                         requestSignal.throwIfAborted();
+                        requestStarted = true;
                         const out = await this.opts.chat.insertOneChat({
                             in: current.input,
                             signal: requestSignal,
@@ -369,15 +387,12 @@ export class ChatSendQueue {
                     }
                     this.startConfirmation(current, owner, signal);
                 }
-                catch (err) {
+                catch {
                     current = {
                         ...current,
-                        status: requestSignal.aborted
-                            ? ChatSendStatus.Interrupted
-                            : ChatSendStatus.Failed,
-                        retry: requestSignal.aborted
-                            ? undefined
-                            : nextQueueRetry(current.retry),
+                        attempted: current.attempted && (requestStarted || !!current.server_id),
+                        status: ChatSendStatus.Failed,
+                        retry: undefined,
                     };
                     if (current.server_id)
                         this.pendingCreates.set(current.id, current);
@@ -387,14 +402,13 @@ export class ChatSendQueue {
                     }
                     catch (storageError) {
                         this.error = storageError;
-                    }
-                    if (this.current(owner, signal) && !request.signal.aborted) {
-                        this.error = err;
                         this.publish();
-                        if (current.retry)
-                            this.scheduleRecovery(current.retry.after);
+                        this.recoverStorage();
+                        return false;
                     }
-                    return false;
+                    // The failed entry is durable and excluded from the creation lane.
+                    // Continue with the next message without a timer or another POST.
+                    return this.current(owner, signal);
                 }
                 finally {
                     this.sends.delete(entry.id);
@@ -406,7 +420,9 @@ export class ChatSendQueue {
     // Retrieval is independent of the room's creation lock. Its per-message
     // lock coordinates retries/recovery across tabs without holding later POSTs.
     startConfirmation(entry, owner, signal) {
-        if (this.confirmations.has(entry.id) || this.waitForRetry(entry)) {
+        const known = entry.server_id && this.confirmed.get(entry.server_id);
+        if (this.confirmations.has(entry.id) ||
+            (!known && this.opts.online?.() === false)) {
             return;
         }
         this.confirmations.add(entry.id);
@@ -417,17 +433,23 @@ export class ChatSendQueue {
             }
             const stored = (await this.opts.store.list(owner)).find((value) => value.id === entry.id);
             if (!stored ||
-                !chatSendCanConfirm(stored) ||
-                this.waitForRetry(stored)) {
+                !stored.server_id ||
+                stored.chat ||
+                (!chatSendCanConfirm(stored) && !this.confirmed.has(stored.server_id))) {
                 return;
             }
             let current = stored;
             try {
-                const out = await this.opts.chat.findOneChat({
-                    id: current.server_id,
-                    signal,
-                });
-                const chat = out.value;
+                const chat = this.confirmed.get(current.server_id) ??
+                    (await this.opts.chat
+                        .findOneChat({ id: current.server_id, signal })
+                        .catch((err) => {
+                        // A room event can arrive while this read is in flight.
+                        const confirmed = this.confirmed.get(current.server_id);
+                        if (confirmed)
+                            return { value: confirmed };
+                        throw err;
+                    })).value;
                 if (!chat ||
                     chat.id !== current.server_id ||
                     chat.owner_id !== owner ||
@@ -457,26 +479,16 @@ export class ChatSendQueue {
                     this.opts.changed?.(chat);
                 }
             }
-            catch (err) {
-                const retry = signal.aborted
-                    ? undefined
-                    : nextQueueRetry(current.retry);
-                if (retry && !current.chat && this.current(owner, signal)) {
-                    this.scheduleRecovery(retry.after);
-                }
+            catch {
                 await this.save({
                     ...current,
-                    retry,
+                    retry: undefined,
                     status: current.chat
                         ? ChatSendStatus.UploadInterrupted
                         : signal.aborted
                             ? ChatSendStatus.Interrupted
                             : ChatSendStatus.Failed,
                 });
-                if (this.current(owner, signal)) {
-                    this.error = err;
-                    this.publish();
-                }
             }
         })
             .catch((err) => {
@@ -681,14 +693,30 @@ function chatSendCanConfirm(entry) {
         (entry.status === ChatSendStatus.Confirming ||
             entry.status === ChatSendStatus.Sending ||
             entry.status === ChatSendStatus.Queued ||
-            entry.status === ChatSendStatus.Interrupted ||
-            entry.status === ChatSendStatus.Failed));
+            entry.status === ChatSendStatus.Interrupted));
 }
 export function chatSendNeedsRetry(entry) {
     return (entry.status === ChatSendStatus.Failed ||
         entry.status === ChatSendStatus.Interrupted ||
         entry.status === ChatSendStatus.UploadInterrupted);
 }
+// Local persistence and reads by a known server ID are safe to retry. An
+// attempted creation without an ID cannot be repeated or silently re-keyed.
+export function chatSendCanRetry(entry) {
+    return (chatSendNeedsRetry(entry) &&
+        (!entry.attempted || !!entry.server_id || !!entry.chat));
+}
+export function chatSendCanRestore(entry) {
+    return (chatSendNeedsRetry(entry) &&
+        entry.attempted &&
+        !entry.server_id &&
+        !entry.chat);
+}
+function chatSendCanCreate(entry) {
+    return (!entry.chat &&
+        !entry.server_id &&
+        (entry.status !== ChatSendStatus.Failed || !!entry.retry));
+}
 export function chatSendCanRemove(entry) {
     if (!entry.chat && entry.server_id) {
         return false;

package/dist/src/core/multi-create.d.ts

@@ -0,0 +1,74 @@
+export declare const multiCreateMaximumEntries = 40;
+export declare const multiCreateConcurrency = 5;
+export declare const MultiCreateStatus: {
+    readonly Pending: "pending";
+    readonly Creating: "creating";
+    readonly Created: "created";
+    readonly Failed: "failed";
+};
+export type MultiCreateStatus = (typeof MultiCreateStatus)[keyof typeof MultiCreateStatus];
+export type MultiCreateCheckpoint = {
+    created_id?: string;
+    on_created?: (id: string) => void;
+    before_request?: () => void;
+};
+export type MultiCreateAttempt = MultiCreateCheckpoint & {
+    idempotency_key: string;
+    signal: AbortSignal;
+};
+export type MultiCreateEntry<Input, Result> = {
+    readonly id: string;
+    readonly input: Input;
+    readonly status: MultiCreateStatus;
+    readonly idempotency_key: string;
+    readonly attempted: boolean;
+    readonly created_id?: string;
+    readonly result?: Result;
+    readonly error?: unknown;
+};
+export type MultiCreateSnapshot<Input, Result> = {
+    readonly entries: readonly MultiCreateEntry<Input, Result>[];
+    readonly running: boolean;
+};
+export type MultiCreateOutcome<Input, Result> = {
+    readonly entries: readonly MultiCreateEntry<Input, Result>[];
+    readonly created: number;
+    readonly failed: number;
+};
+export declare class MultiCreatePool {
+    readonly capacity: number;
+    private active;
+    private waiting;
+    constructor(capacity?: number);
+    run(run: () => Promise<void>): Promise<void>;
+}
+export type MultiCreateOptions<Input, Result> = {
+    run: (input: Input, attempt: MultiCreateAttempt) => Promise<Result>;
+    pool?: MultiCreatePool;
+    before_request?: () => void;
+    on_failed?: (entry: MultiCreateEntry<Input, Result>) => void;
+    on_settled?: (outcome: MultiCreateOutcome<Input, Result>) => void;
+};
+export declare class MultiCreator<Input, Result> {
+    private readonly opts;
+    private entries;
+    private listeners;
+    private running;
+    private controller;
+    private completion;
+    constructor(opts: MultiCreateOptions<Input, Result>);
+    get snapshot(): MultiCreateSnapshot<Input, Result>;
+    subscribe(listener: (snapshot: MultiCreateSnapshot<Input, Result>) => void): () => void;
+    add(input: Input): string;
+    edit(id: string, input: Input): boolean;
+    remove(id: string): boolean;
+    start(): Promise<void>;
+    private begin;
+    retry(id: string, input?: Input): Promise<void>;
+    whenIdle(): Promise<void>;
+    cancel(): void;
+    private run;
+    private replace;
+    private publish;
+    private notify;
+}

package/dist/src/core/multi-create.js

@@ -0,0 +1,203 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+export const multiCreateMaximumEntries = 40;
+export const multiCreateConcurrency = 5;
+export const MultiCreateStatus = {
+    Pending: "pending",
+    Creating: "creating",
+    Created: "created",
+    Failed: "failed",
+};
+// Share one pool between batches to keep the application's total concurrency bounded.
+export class MultiCreatePool {
+    capacity;
+    active = 0;
+    waiting = [];
+    constructor(capacity = multiCreateConcurrency) {
+        this.capacity = capacity;
+        if (!Number.isInteger(capacity) || capacity < 1)
+            throw new RangeError("Invalid creation concurrency.");
+    }
+    async run(run) {
+        await new Promise((resolve) => {
+            const enter = () => {
+                this.active++;
+                resolve();
+            };
+            if (this.active < this.capacity)
+                enter();
+            else
+                this.waiting.push(enter);
+        });
+        try {
+            await run();
+        }
+        finally {
+            this.active--;
+            this.waiting.shift()?.();
+        }
+    }
+}
+const sharedMultiCreatePool = new MultiCreatePool();
+// Temporary, app-owned batch. No persistence, automatic retries or transactions.
+// Removing presentation subscribers does not cancel a submitted batch.
+export class MultiCreator {
+    opts;
+    entries = [];
+    listeners = new Set();
+    running = false;
+    controller = new AbortController();
+    completion = Promise.resolve();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get snapshot() {
+        return { entries: this.entries, running: this.running };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.snapshot);
+        return () => this.listeners.delete(listener);
+    }
+    add(input) {
+        if (this.running || this.entries.length >= multiCreateMaximumEntries)
+            throw new RangeError("Creation batch is full or running.");
+        const id = crypto.randomUUID();
+        this.entries = [
+            ...this.entries,
+            {
+                id,
+                input: structuredClone(input),
+                status: MultiCreateStatus.Pending,
+                idempotency_key: crypto.randomUUID(),
+                attempted: false,
+            },
+        ];
+        this.publish();
+        return id;
+    }
+    edit(id, input) {
+        const entry = this.entries.find((entry) => entry.id === id);
+        if (this.running || entry?.status !== MultiCreateStatus.Pending)
+            return false;
+        this.replace({ ...entry, input: structuredClone(input) });
+        return true;
+    }
+    remove(id) {
+        if (this.running ||
+            !this.entries.some((entry) => entry.id === id && entry.status === MultiCreateStatus.Pending))
+            return false;
+        this.entries = this.entries.filter((entry) => entry.id !== id);
+        this.publish();
+        return true;
+    }
+    start() {
+        if (this.running)
+            return this.completion;
+        const pending = this.entries.filter((entry) => entry.status === MultiCreateStatus.Pending);
+        return this.begin(pending);
+    }
+    begin(pending) {
+        if (!pending.length)
+            return Promise.resolve();
+        this.running = true;
+        this.controller = new AbortController();
+        this.publish();
+        this.completion = this.run(pending);
+        return this.completion;
+    }
+    retry(id, input) {
+        const entry = this.entries.find((entry) => entry.id === id);
+        if (this.running || entry?.status !== MultiCreateStatus.Failed)
+            return this.completion;
+        // Explicit user retry is a new creation attempt when no ID was acknowledged.
+        // A known ID always resumes retrieval with the original request key.
+        const next = {
+            ...entry,
+            input: input === undefined ? entry.input : structuredClone(input),
+            idempotency_key: entry.created_id
+                ? entry.idempotency_key
+                : crypto.randomUUID(),
+            status: MultiCreateStatus.Pending,
+            error: undefined,
+        };
+        this.replace(next);
+        return this.begin([next]);
+    }
+    whenIdle() {
+        return this.completion;
+    }
+    cancel() {
+        this.controller.abort();
+    }
+    async run(pending) {
+        const signal = this.controller.signal;
+        const pool = this.opts.pool ?? sharedMultiCreatePool;
+        await Promise.all(pending.map((entry) => pool.run(async () => {
+            let current = {
+                ...entry,
+                status: MultiCreateStatus.Creating,
+            };
+            this.replace(current);
+            try {
+                signal.throwIfAborted();
+                this.opts.before_request?.();
+                const result = await this.opts.run(structuredClone(current.input), {
+                    signal,
+                    idempotency_key: current.idempotency_key,
+                    created_id: current.created_id,
+                    before_request: () => {
+                        signal.throwIfAborted();
+                        this.opts.before_request?.();
+                        current = { ...current, attempted: true };
+                        this.replace(current);
+                    },
+                    on_created: (id) => {
+                        current = { ...current, created_id: id };
+                        this.replace(current);
+                    },
+                });
+                this.replace({
+                    ...current,
+                    status: MultiCreateStatus.Created,
+                    result,
+                    error: undefined,
+                });
+            }
+            catch (error) {
+                current = { ...current, status: MultiCreateStatus.Failed, error };
+                this.replace(current);
+                this.notify(() => this.opts.on_failed?.(current));
+            }
+        })));
+        this.running = false;
+        this.publish();
+        const ids = new Set(pending.map((entry) => entry.id));
+        const entries = this.entries.filter((entry) => ids.has(entry.id));
+        this.notify(() => this.opts.on_settled?.({
+            entries,
+            created: entries.filter((entry) => entry.status === MultiCreateStatus.Created).length,
+            failed: entries.filter((entry) => entry.status === MultiCreateStatus.Failed).length,
+        }));
+    }
+    replace(entry) {
+        this.entries = this.entries.map((value) => value.id === entry.id ? entry : value);
+        this.publish();
+    }
+    publish() {
+        for (const listener of this.listeners)
+            this.notify(() => listener(this.snapshot));
+    }
+    notify(run) {
+        // Presentation errors cannot turn a successful creation into a failed POST.
+        try {
+            run();
+        }
+        catch (err) {
+            console.error("Multi-creation observer failed.", err);
+        }
+    }
+}

package/dist/src/index.d.ts

@@ -8,6 +8,7 @@ export * from "./contacts/contacts.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/id.js";
+export * from "./core/multi-create.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
 export * from "./core/queue-store.js";

package/dist/src/index.js

@@ -8,6 +8,7 @@ export * from "./contacts/contacts.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/id.js";
+export * from "./core/multi-create.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
 export * from "./core/queue-store.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.110",
+  "version": "0.0.112",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {