@fabriktor/fx 0.0.111 → 0.0.113

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.js

@@ -50,7 +50,9 @@ export class ChatSendQueue {
     }
     get snapshot() {
         return {
-            entries: this.entries,
+            entries: this.entries.filter((entry) => !this.cancellations.has(entry.id) ||
+                !!entry.server_id ||
+                !!entry.chat),
             confirmed: [...this.confirmed.values()],
             confirmed_sequences: Object.fromEntries(this.confirmedSequences),
             error: this.error,
@@ -268,6 +270,7 @@ export class ChatSendQueue {
             return;
         }
         this.cancellations.add(id);
+        this.publish();
         try {
             // Finish a pending local save before removing its durable record. The
             // cancellation flag prevents this tab from starting that message meanwhile.
@@ -388,6 +391,11 @@ export class ChatSendQueue {
                     this.startConfirmation(current, owner, signal);
                 }
                 catch {
+                    // remove() owns deliberate cancellation and removes the durable entry
+                    // under this same room lock. Do not publish a transient send failure.
+                    if (this.cancellations.has(entry.id) && !current.server_id) {
+                        return false;
+                    }
                     current = {
                         ...current,
                         attempted: current.attempted && (requestStarted || !!current.server_id),

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.111",
+  "version": "0.0.113",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {