@docstack/client 0.1.8 → 0.3.0

package/lib/core/transaction-engine/handle.d.ts

@@ -0,0 +1,165 @@
+import { Document } from "@docstack/shared";
+import type ClientStack from "../stack.js";
+import { TransactionStage, StagedEntry } from "./stage.js";
+import { MangoSort } from "./overlay.js";
+import type { TransactionEngine, TransactionCommitReport } from "./index.js";
+export type TransactionStatus = "open" | "committed" | "discarded" | "partial";
+/**
+ * One transaction: a private write journal plus a read view that overlays it on
+ * committed state (ADR-0039).
+ *
+ * Writes through the handle are validated at the call site (the sweep - failing
+ * stages nothing) and stage in memory; nothing reaches the database until
+ * {@link commit}, which flushes the journal as one batch through the stack's full
+ * authoring pipeline. Reads through the handle see the journal; `stack.db`, other
+ * handles, replication and live subscriptions see only committed state.
+ *
+ * @example
+ * ```typescript
+ * const t = stack.beginTransaction();
+ * await t.createDoc(null, "Task", { title: "write-up" });
+ * await t.db.put({ ...(await t.db.get("Task-77")), done: true });
+ * const drafted = await t.findDocuments({ "~class": { $eq: "Task" } });
+ * const report = await t.commit();   // or stack.commit(t)
+ * ```
+ */
+export declare class TransactionHandle {
+    readonly id: string;
+    /** @internal */
+    readonly stage: TransactionStage;
+    /** @internal - ids this handle minted, counted into the id counter after commit. */
+    readonly mintedIds: Set<string>;
+    /**
+     * True for handles DocStack mints for its own machinery (patch application,
+     * ADR-0042). Internal handles may stage class models; public ones refuse them.
+     * @internal
+     */
+    readonly internal: boolean;
+    private statusValue;
+    private readonly stack;
+    private readonly engine;
+    /** The db-like surface: staged writes, overlaid reads. */
+    readonly db: TransactionDb;
+    /** @internal */
+    constructor(stack: ClientStack, engine: TransactionEngine, id: string, internal?: boolean);
+    get status(): TransactionStatus;
+    /** @internal */
+    setStatus(status: TransactionStatus): void;
+    stagedCount(): number;
+    /** @internal */
+    assertWritable(operation: string): void;
+    /**
+     * Stages a write. The sweep runs first: a document that fails validation, policy,
+     * or the locked-stack check is not staged and the journal is untouched.
+     * @internal
+     */
+    stageWrite(doc: Document, op?: "write" | "delete"): Promise<StagedEntry>;
+    /**
+     * Creates or updates a document in the transaction - `stack.createDoc`'s UX with
+     * a staged destination: `docId: null` mints an id, an existing id merges params
+     * over the overlay-visible document.
+     */
+    createDoc(docId: string | null, type: string, params: {
+        [key: string]: any;
+    }): Promise<Document>;
+    /** Batch counterpart of {@link createDoc}; validated sequentially, fail-fast. */
+    createDocs(docs: {
+        docId: string | null;
+        params: {
+            [key: string]: any;
+        };
+    }[], type: string): Promise<Document[]>;
+    /** Soft-deletes in the transaction: the overlay stops showing the document under the default `active: true`. */
+    deleteDocument(docId: string): Promise<boolean>;
+    /** The stack's polished read, against this transaction's view. */
+    findDocuments<T extends Document = Document>(selector: {
+        [key: string]: any;
+    }, fields?: string[], skip?: number, limit?: number, sort?: MangoSort): Promise<{
+        [key: string]: any;
+        docs: T[];
+    }>;
+    /**
+     * SQL against this transaction's view. The executor reaches data only through
+     * stack APIs, so a facade routes them at the overlay; LIMIT/OFFSET pushdown and
+     * sort indexes are disabled while staged - staged documents exist in no index,
+     * so windows and orderings must be computed after the merge.
+     */
+    query(sql: string, ...params: any[]): Promise<{
+        rows: any;
+        ast: (import("@docstack/shared").SelectAST | import("@docstack/shared").UnionAST)[];
+    }>;
+    /** Flushes the journal - sugar for `stack.commit(t)`. */
+    commit(): Promise<TransactionCommitReport>;
+    /** Drops the journal - sugar for `stack.discardTransaction(t)`. */
+    discard(): void;
+}
+/**
+ * The handle's db-like surface. Writes stage; reads overlay. Not a Proxy over the
+ * guarded db on purpose: this object *has no* adapter methods or escape hatches to
+ * forward, so staging cannot become a fourth door around the authoring path.
+ */
+export declare class TransactionDb {
+    private readonly stack;
+    private readonly handle;
+    /** @internal */
+    constructor(stack: ClientStack, handle: TransactionHandle);
+    get(docId: string, options?: any): Promise<Document>;
+    bulkGet(request: {
+        docs: {
+            id: string;
+            rev?: string;
+        }[];
+    }): Promise<{
+        results: any[];
+    }>;
+    /**
+     * Raw-style Mango find over the transaction's view. Like `stack.db.find`, this
+     * skips the read pipeline (no policy filter, no decryption of committed rows);
+     * `findDocuments` on the handle is the polished read.
+     */
+    find(query: {
+        selector: {
+            [key: string]: any;
+        };
+        fields?: string[];
+        skip?: number;
+        limit?: number;
+        sort?: any;
+    }): Promise<{
+        docs: Document[];
+    }>;
+    put(doc: Document, options?: any): Promise<{
+        ok: true;
+        id: string;
+        rev?: string;
+        staged: true;
+    }>;
+    post(doc: Document): Promise<{
+        ok: true;
+        id: string;
+        rev?: string;
+        staged: true;
+    }>;
+    /** Hard removal, staged: the commit writes `_deleted: true`. Soft deletion is `handle.deleteDocument`. */
+    remove(doc: {
+        _id: string;
+        _rev?: string;
+    } | string, rev?: string): Promise<{
+        ok: true;
+        id: string;
+        staged: true;
+    }>;
+    /**
+     * Stages a batch. Validated sequentially - the first refusal unwinds every entry
+     * this call staged, so a failing batch stages nothing. Documents stage before
+     * relations, mirroring the commit batch, so a relation and its endpoint can
+     * arrive in one array in any order.
+     */
+    bulkDocs(docs: Document[] | {
+        docs: Document[];
+    }, options?: any): Promise<{
+        ok: true;
+        id: string;
+        staged: true;
+    }[]>;
+}

package/lib/core/transaction-engine/index.d.ts

@@ -0,0 +1,82 @@
+import type ClientStack from "../stack.js";
+import { TransactionHandle } from "./handle.js";
+export { TransactionHandle, TransactionDb } from "./handle.js";
+export type { TransactionStatus } from "./handle.js";
+export { TransactionStage } from "./stage.js";
+export type { StagedEntry, StagedOp } from "./stage.js";
+export { stageCoversSelector, mergeStageIntoResults, widenProjection } from "./overlay.js";
+export { classFromStage } from "./sweep.js";
+export { TransactionsDisabledError, TransactionStateError, TransactionValidationError, TransactionConflictError, TransactionUnsupportedDocError, } from "./errors.js";
+/** What one commit did, and on what guarantee. */
+export type TransactionCommitReport = {
+    transactionId: string;
+    /** Documents that landed, with their new revisions. */
+    written: {
+        id: string;
+        rev: string;
+    }[];
+    /** Documents that did not - possible only on adapters where `atomicBatch` is false. */
+    failed: {
+        id: string;
+        error: string;
+        name?: string;
+    }[];
+    /** Journal size at the moment commit ran. */
+    stagedCount: number;
+    durationMs: number;
+    /**
+     * The storage adapter's honest guarantee for this commit: `atomicBatch: true`
+     * means the batch landed (or failed) as one storage transaction; `false` means
+     * per-document results, mitigated by the rev pre-flight but not eliminated.
+     */
+    adapter: {
+        name: string;
+        atomicBatch: boolean;
+    };
+};
+/**
+ * Named write transactions for one stack (ADR-0039).
+ *
+ * Enabled per stack by `transactions: true` in its configuration - the flag only
+ * unlocks {@link begin}; direct writes stay immediate, and the framework's own
+ * writers (scheduler, jobs, sync) always write directly. The stage lives above the
+ * plugin: nothing a transaction does touches the database until commit, and commit
+ * is exactly one `stack.db.bulkDocs` through the full authoring pipeline.
+ */
+export declare class TransactionEngine {
+    private readonly stack;
+    private readonly enabled;
+    private readonly handles;
+    /** Commits serialize here so one commit's rev pre-flight cannot be invalidated by another's write. */
+    private commitChain;
+    constructor(stack: ClientStack, enabled: boolean);
+    isEnabled(): boolean;
+    /** How many transactions are currently open (or partial). */
+    openCount(): number;
+    begin(): TransactionHandle;
+    /**
+     * Opens a transaction for DocStack's own machinery - patch application
+     * (ADR-0042). Independent of the `transactions: true` config gate (the flag
+     * governs the consumer feature, not the framework's internals) and permitted to
+     * stage class models: an internal handle claims staged validation and a single
+     * class-write batch, never propagation atomicity.
+     * @internal
+     */
+    beginInternal(): TransactionHandle;
+    private resolve;
+    /**
+     * Drops a transaction's journal. Idempotent, and a no-op on a handle already in
+     * a terminal state - discarding what is already gone is not an error.
+     */
+    discard(t: TransactionHandle | string): void;
+    /** Discards every open transaction - what `close()` and `reset()` do. */
+    discardAll(): void;
+    /**
+     * Flushes a transaction's journal as one batch through the stack's authoring
+     * pipeline. Refusals - validation, or a staged document whose base revision
+     * moved - throw with nothing persisted and the transaction still open.
+     */
+    commit(t: TransactionHandle | string): Promise<TransactionCommitReport>;
+    private commitNow;
+    private adapterInfo;
+}

package/lib/core/transaction-engine/overlay.d.ts

@@ -0,0 +1,66 @@
+import { Document } from "@docstack/shared";
+import { TransactionStage } from "./stage.js";
+/** The sort shape `findDocuments` accepts. */
+export type MangoSort = {
+    [field: string]: "asc" | "desc";
+}[] | string[];
+/**
+ * True when a query with this selector could see documents this stage holds.
+ *
+ * Derived from the selector's `~class` / `~domain` constraint against the stage's
+ * partitions; a selector naming no class is answered conservatively. This is the
+ * per-query fast path: a find over a class the transaction never touched runs
+ * exactly as it would outside the transaction.
+ */
+export declare const stageCoversSelector: (stage: TransactionStage, selector: {
+    [key: string]: any;
+}) => boolean;
+/**
+ * Fields the widened committed query (and the staged docs) must carry beyond the
+ * caller's projection, so masking, sorting and the read pipeline can work; the
+ * extras are stripped again after the merge.
+ */
+export declare const widenProjection: (fields: string[] | undefined, sort: MangoSort | undefined) => {
+    queryFields: string[] | undefined;
+    extras: string[];
+};
+/**
+ * Merges a stage into a committed query result: every staged id masks its committed
+ * row (superseded and deleted alike), staged writes matching the selector join the
+ * set, then sort, window and projection apply in memory - the database's index can
+ * never see a staged document, so the window has to be computed after the union.
+ *
+ * `committedDocs` must come from a query WITHOUT skip/limit (the mask changes what
+ * the window contains) and carrying `widenProjection`'s fields.
+ */
+export declare const mergeStageIntoResults: (stage: TransactionStage, selector: {
+    [key: string]: any;
+}, committedDocs: Document[], options?: {
+    sort?: MangoSort;
+    skip?: number;
+    limit?: number;
+    fields?: string[];
+    extras?: string[];
+}) => Document[];
+/** A PouchDB-shaped `not_found`, so overlay reads refuse like the database does. */
+export declare const notFoundError: (id: string) => any;
+/**
+ * Read-your-writes for a point read: a staged delete is a 404, a staged write is the
+ * authored plaintext (its `_rev` is the base revision - the revision the commit will
+ * replace), anything else is the stack's ordinary decrypting read.
+ */
+export declare const overlayGet: (stack: {
+    db: any;
+}, stage: TransactionStage, id: string, options?: any) => Promise<Document>;
+/** `bulkGet` counterpart of {@link overlayGet}, preserving request order. */
+export declare const overlayBulkGet: (stack: {
+    db: any;
+}, stage: TransactionStage, request: {
+    docs: {
+        id: string;
+        rev?: string;
+    }[];
+    [key: string]: any;
+}) => Promise<{
+    results: any[];
+}>;

package/lib/core/transaction-engine/stage.d.ts

@@ -0,0 +1,50 @@
+import { Document } from "@docstack/shared";
+/** What one staged entry means for its document id. */
+export type StagedOp = "write" | "delete";
+export interface StagedEntry {
+    /** The authored document, plaintext, cloned at stage time. */
+    doc: Document;
+    /** The winning revision the entry was staged against; absent for a new document. */
+    baseRev?: string;
+    op: StagedOp;
+    /** True when the id did not exist (in stage or store) when first staged. */
+    isNew: boolean;
+    stagedAt: number;
+}
+/**
+ * The write journal of one transaction: authored documents keyed by id, in memory.
+ *
+ * Also partitioned by class (`~class`, or `~domain` for relations) so a read can ask
+ * "could this stage affect a query over class X" in O(1) - the overlay only pays the
+ * merge for queries whose class the transaction actually touched (ADR-0039).
+ */
+export declare class TransactionStage {
+    private entries;
+    private partitions;
+    private partitionKeys;
+    /**
+     * Stages an entry. Re-staging an id replaces the document but keeps the original
+     * `baseRev` and `isNew` - the conflict check is against the world as it was when
+     * the transaction first touched the id, not against its own previous draft.
+     */
+    set(id: string, entry: StagedEntry): void;
+    get(id: string): StagedEntry | undefined;
+    has(id: string): boolean;
+    get size(): number;
+    ids(): string[];
+    /** Entries in stage order (insertion order of first staging). */
+    values(): StagedEntry[];
+    hasPartition(name: string): boolean;
+    /** Keeps only the given ids - what a partial commit leaves behind. */
+    retain(ids: Set<string>): void;
+    /**
+     * A point-in-time copy of the journal, for {@link restore}. Used by the patch
+     * chain (ADR-0044) to unwind exactly one patch's staging - a pre-apply job's
+     * writes included - when a locked refusal converts that patch to a deferral
+     * while the already-staged prefix goes on to commit.
+     */
+    snapshot(): Map<string, StagedEntry>;
+    restore(snapshot: Map<string, StagedEntry>): void;
+    remove(id: string): void;
+    clear(): void;
+}

package/lib/core/transaction-engine/sweep.d.ts

@@ -0,0 +1,25 @@
+import Class from "../class.js";
+import type ClientStack from "../stack.js";
+import { TransactionStage, StagedEntry } from "./stage.js";
+/**
+ * Resolves a class from the transaction's own stage: the ADR-0043 rule
+ * (the batch outranks the store - it is what is about to be committed) applied to
+ * staging. A patch chain's job can create documents of a class an earlier patch
+ * staged (ADR-0044), and the sweep must judge them by that staged model, not by a
+ * committed predecessor or a not-found. Built DETACHED - `Class.get` + `setModel`,
+ * never `buildFromModel`, which writes rev-less models (ADR-0043).
+ */
+export declare const classFromStage: (stack: ClientStack, stage: TransactionStage, className: string) => Class | null;
+/**
+ * The validation sweep - the transaction's atomicity boundary in practice.
+ *
+ * Runs read-only checks against public stack APIs: it decides whether a document
+ * *could* be written, and touches nothing. Stage time runs it so a bad write fails at
+ * the call site with zero consequences; commit re-runs it so the batch is judged
+ * against the world as it stands at commit. The commit-time pipeline (the plugin's
+ * `bulkDocs`) remains the sole authority - this sweep is a deliberate subset, and a
+ * document it passes can still be refused there, atomically for the whole batch.
+ */
+export declare const sweepEntry: (stack: ClientStack, stage: TransactionStage, entry: StagedEntry, options?: {
+    allowClassModels?: boolean;
+}) => Promise<void>;

package/lib/index.d.ts

@@ -18,9 +18,19 @@ export type { SchedulerOptions, SchedulerHost, JobScheduleState, TickReport, Ski
  * application hands over, so DocStack never learns about Google Drive, Firestore or
  * anything else, and no consumer pays for a transport it does not use.
  */
-export { StackSyncHandle, DocStackSyncHandle, SyncSchemaMismatchError, SYNC_META_DOC_ID, readRemoteSchemaVersion, publishSchemaVersion, createReplicationFilter, isInternalDoc, resolveInternalClasses, createClassFilter, hasClassRules, DATA_MODEL_CLASSES, withFilterIdentity, describeFilter, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, INTERNAL_DOC_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, StackWriteGuardError, StackLockedError, deriveKeyId, isEncryptedPayload, deriveTenantScope, classTenants, } from "./core/index.js";
+export { StackSyncHandle, DocStackSyncHandle, SyncSchemaMismatchError, SYNC_META_DOC_ID, readRemoteSchemaVersion, readRemoteConsumerSchemaVersion, publishSchemaVersion, createReplicationFilter, isInternalDoc, resolveInternalClasses, createClassFilter, hasClassRules, DATA_MODEL_CLASSES, withFilterIdentity, describeFilter, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, INTERNAL_DOC_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, StackWriteGuardError, StackLockedError, StackScopeMismatchError, deriveKeyId, isEncryptedPayload, deriveTenantScope, classTenants, } from "./core/index.js";
 export { SYSTEM_SEEDED_DOC_IDS, collectQueryClasses } from "./core/index.js";
 export type { EncryptedPayload, ClassBuildOptions } from "./core/index.js";
+/**
+ * Named write transactions (ADR-0039).
+ *
+ * Opt-in per stack via `transactions: true`. A handle stages validated writes in
+ * memory and reads its own staged state overlaid on committed state; `commit`
+ * flushes the journal as one batch through the full authoring pipeline, and the
+ * report states the storage adapter's honest atomicity guarantee.
+ */
+export { TransactionEngine, TransactionHandle, TransactionDb, TransactionsDisabledError, TransactionStateError, TransactionValidationError, TransactionConflictError, TransactionUnsupportedDocError, } from "./core/index.js";
+export type { TransactionCommitReport, TransactionStatus } from "./core/index.js";
 /**
  * Moving application content between stacks, without the datamodel that describes it.
  */
@@ -37,5 +47,5 @@ export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSy
  * Note that `Document` shadows the DOM's global `Document` in whichever module imports
  * it; alias it (`import type { Document as DocStackDocument }`) in code that needs both.
  */
-export type { AttributeType, AttributeTypeConfig, AttributeModel, ClassModel, DomainModel, TriggerModel, Document, RelationDocument, Patch, SelectAST, UnionAST, ClientCredentials, DocstackReady, StackConfig, StackOptions, } from "@docstack/shared";
+export type { AttributeType, AttributeTypeConfig, AttributeModel, ClassModel, DomainModel, TriggerModel, Document, RelationDocument, Patch, PatchJob, SelectAST, UnionAST, ClientCredentials, DocstackReady, StackConfig, StackOptions, } from "@docstack/shared";
 export default DocStack;