@docstack/client 0.1.4 → 0.1.6

package/lib/core/index.d.ts

@@ -5,6 +5,8 @@ import { Trigger } from "./trigger/index.js";
 import { JobEngine } from "./job-engine/index.js";
 import Attribute from './attribute.js';
 import { AttributeType, ClientCredentials, StackConfig } from "@docstack/shared";
+import { DocStackSyncHandle } from './sync/index.js';
+import type { DocStackSyncOptions } from './sync/index.js';
 /**
  * The main entry point for the DocStack client library.
  *
@@ -43,8 +45,94 @@ declare class DocStack extends EventTarget {
     private store;
     /** Array of all initialized ClientStack instances. */
     stacks: ClientStack[];
+    /**
+     * Stacks currently being opened, by name.
+     *
+     * `stacks` only gains an entry once `ClientStack.create` resolves, so it cannot answer
+     * "is this one already on its way?". Without that, {@link addStack}'s guard is a check
+     * followed by an `await` - not atomic - and two concurrent callers each open a handle
+     * on the same database. See ADR-0022.
+     */
+    private pendingStacks;
+    /** The handle from the last {@link sync} call. */
+    private syncHandle?;
     private logger;
-    private addStack;
+    /**
+     * Splits a {@link StackConfig} into the connection string and the options a stack
+     * is created with.
+     *
+     * Everything the caller passed is forwarded - including `adapter` and any
+     * adapter-specific keys - so a stack can be opened on a transport other than the
+     * default one.
+     *
+     * @param config - A stack name, or a full configuration object.
+     * @returns The connection string and the resolved {@link StackOptions}.
+     */
+    private static resolveStackConfig;
+    /**
+     * Opens a stack and adds it to this instance.
+     *
+     * Public because an application's set of databases is not always known at startup:
+     * a workspace joined at runtime needs its own database, and its own replication
+     * pair, without tearing down the stacks already open. Adding a stack that is
+     * already open returns the existing instance rather than opening a second handle
+     * on the same database.
+     *
+     * Dispatches `stack-added` with the new stack in `detail`.
+     *
+     * @param config - A stack name, or a full configuration object.
+     * @returns The stack, initialized and ready.
+     *
+     * @example
+     * ```typescript
+     * const stack = await docstack.addStack({ name: `ws-${workspace.slug}`, patches });
+     * await stack.sync({ remote: () => driveFor(workspace) });
+     * ```
+     */
+    addStack: (config: StackConfig) => Promise<ClientStack>;
+    /**
+     * Closes a stack and drops it from this instance.
+     *
+     * Closing cancels the stack's replication and releases its listeners; the data on
+     * disk is left alone unless `destroy` is set, which is what leaving a workspace for
+     * good looks like.
+     *
+     * Dispatches `stack-removed` with the stack's name in `detail`.
+     *
+     * @param name - The stack name or connection string.
+     * @param options - `destroy: true` also deletes the underlying database.
+     * @returns `true` if a stack was removed, `false` if there was none by that name.
+     */
+    removeStack: (name: string, options?: {
+        destroy?: boolean;
+    }) => Promise<boolean>;
+    /**
+     * Starts replication for every open stack against one transport.
+     *
+     * The `remote` resolver is called once per stack, which is what makes a
+     * database-per-workspace application a single call rather than a loop the
+     * application has to keep in step with its own stack list.
+     *
+     * @param options - See {@link DocStackSyncOptions}. `stacks` narrows it to a subset.
+     * @returns A handle holding every stack's replication.
+     *
+     * @example
+     * ```typescript
+     * const sync = await docstack.sync({
+     *     remote: (stack) => new PouchDB(stack.name, { adapter: 'googledrive', accessToken }),
+     * });
+     * sync.addEventListener('status', () => render(sync.getStatus()));
+     * ```
+     */
+    sync: (options: DocStackSyncOptions) => Promise<DocStackSyncHandle>;
+    /**
+     * Returns the handle from the last {@link sync} call, or `null`.
+     */
+    getSyncHandle: () => DocStackSyncHandle | null;
+    /**
+     * Stops replication on every stack.
+     */
+    cancelSync: () => void;
     private initStacks;
     /**
      * Resets all initialized stacks.
@@ -185,4 +273,21 @@ declare class DocStack extends EventTarget {
  * @module @docstack/client
  */
 export { ClientStack, Trigger, Class, Attribute, Domain, JobEngine };
+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, } from "./sync/index.js";
+export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSyncOptions, RemoteResolver, SyncMetaDoc, InternalDocFilterOptions, ClassFilterOptions, } from "./sync/index.js";
+export type { ClassBuildOptions } from "./class.js";
+export { CONTENT_EXPORT_FORMAT, META_CLASSES, isContentClassName, isContentDocument, isContentRelation, stripTransientFields, } from "./content-transfer.js";
+export type { ContentExport, ContentExportOptions, ContentImportOptions, ContentImportReport, ContentImportIssue, } from "./content-transfer.js";
+export { SYSTEM_SEEDED_DOC_IDS } from "./datamodel/index.js";
+export { collectQueryClasses } from "./query-engine/index.js";
+export { StackWriteGuardError } from "./guarded-db.js";
+export { StackLockedError } from "../plugins/pouchdb.js";
+/**
+ * Key-identity helpers, for applications that re-key a database.
+ *
+ * `deriveKeyId` names a key the same way stored payloads do, so an application can tell
+ * which of its keys a field belongs to without holding any of them.
+ */
+export { deriveKeyId, isEncryptedPayload } from "./crypto-engine/index.js";
+export type { EncryptedPayload } from "./crypto-engine/index.js";
 export { DocStack };

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

@@ -28,11 +28,35 @@ export type PolicyOperation = "read" | "write";
 export declare class PolicyEngine {
     /** Reference to the parent stack for database and session access. */
     private readonly stack;
+    /**
+     * Every `~Policy` document, loaded once and reused across evaluations.
+     *
+     * `isReadableDocument` runs once per document a read returns, and it used to re-fetch
+     * the policy list from the database each time - the dominant cost of every read path.
+     * The list is invalidated on any write that touches a `~Policy` document: the write
+     * path calls {@link invalidatePolicyCache} synchronously (see StackPlugin), and the
+     * stack's shared changes feed calls it again for out-of-band writes such as another
+     * tab's. `null` means not loaded.
+     */
+    private allPoliciesCache;
+    /**
+     * Compiled policy rules, keyed by their source text.
+     *
+     * A rule is evaluated once per policy per document, and `new Function` is a full
+     * compile each time. The source text is the key - not the policy id - so two policies
+     * sharing a rule share the compilation, and an edited rule is simply a new key.
+     */
+    private compiledRules;
     /**
      * Creates a new PolicyEngine instance.
      * @param stack - The parent ClientStack instance
      */
     constructor(stack: ClientStack);
+    /**
+     * Drops the cached policy list so the next evaluation re-reads it.
+     * Called by the write path and the changes feed whenever a `~Policy` document lands.
+     */
+    invalidatePolicyCache(): void;
     /**
      * Gets the current authentication session proof.
      * @returns The session proof, or undefined if not authenticated
@@ -61,6 +85,17 @@ export declare class PolicyEngine {
     private evaluateRule;
     private filterPoliciesForSession;
     private authorize;
+    /**
+     * Whether any policy applies to a class - i.e. whether reads of it are filtered.
+     *
+     * Lets the query engine know when a database-level LIMIT is safe: with no
+     * applicable policies, no row fetched within the limit can be dropped afterwards.
+     * Cheap once the policy list is cached.
+     *
+     * @param targetClass - The class name or id.
+     * @returns `true` if at least one policy targets the class.
+     */
+    hasPoliciesFor(targetClass: string): Promise<boolean>;
     /**
      * Ensures write access is allowed for a document of the given class.
      * Throws an error if no policy permits the write operation.

package/lib/core/query-engine/classes.d.ts

@@ -0,0 +1,24 @@
+import type { SelectAST, UnionAST } from "@docstack/shared";
+/**
+ * Collects the class names a parsed query reads.
+ *
+ * Deliberately generic: rather than enumerating the node types that can hold a nested
+ * query - `scalar_subquery`, `exists_expr`, the right-hand side of `IN` - it walks the
+ * whole graph and harvests every `select` node it finds. A new subquery form is then
+ * covered on the day it is added, rather than on the day someone notices a stale list.
+ *
+ * @param ast - The `ast` from {@link ClientStack.query}.
+ * @returns The class names read, or `null` when the query reads a source that is not a
+ * named class. That distinction is the contract: `[]` means *this query reads nothing* -
+ * `SELECT 1` - and it is safe to subscribe to nothing; `null` means *I cannot account for
+ * this*, and the caller should fail open rather than watch an incomplete set.
+ *
+ * @example
+ * ```typescript
+ * const { rows, ast } = await stack.query("SELECT * FROM Task JOIN Project ON …");
+ * collectQueryClasses(ast);         // ["Task", "Project"]
+ * collectQueryClasses([]);          // []   - reads nothing
+ * collectQueryClasses(null);        // null - unknown, fail open
+ * ```
+ */
+export declare const collectQueryClasses: (ast: (SelectAST | UnionAST)[] | null | undefined) => string[] | null;

package/lib/core/query-engine/executor.d.ts

@@ -12,3 +12,14 @@ import ClientStack from '../stack.js';
  * @throws {Error} If a table specified in the query is not found.
  */
 export declare function executePlan(stack: ClientStack, plan: any, params: any, outerRow?: any, outerAliases?: any): Promise<any>;
+/**
+ * Executes a plan as an async stream of rows.
+ *
+ * A single-table plan with no aggregation, DISTINCT, ORDER BY, or subqueries streams
+ * for real: rows ride `findDocumentsIterator`'s keyset pages, get the WHERE re-check
+ * and projection per row, and honor OFFSET/LIMIT by counting - peak memory is one
+ * batch regardless of result size, and a LIMIT stops the underlying scan early. Any
+ * other plan falls back to `executePlan` and yields from the materialized result, so
+ * the API is uniform even where streaming isn't.
+ */
+export declare function executePlanStream(stack: ClientStack, plan: any, params: any): AsyncGenerator<any, void, unknown>;

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

@@ -1,4 +1,5 @@
 export { parse } from "./parser.js";
 export type { SelectAST, UnionAST } from "@docstack/shared";
 export { createPlan } from "./planner.js";
-export { executePlan } from "./executor.js";
+export { executePlan, executePlanStream } from "./executor.js";
+export { collectQueryClasses } from "./classes.js";

package/lib/core/query-engine/planner.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Whether a column name is safe to hand to Mango - as a selector key, a sort field,
+ * or a projection field. See {@link PUSHABLE_COLUMN_RE} and {@link UNPUSHABLE_COLUMNS}.
+ */
+export declare function isPushableColumnName(name: any): boolean;
+/**
+ * Checks if a predicate is a simple binary expression that can be converted
+ * directly into a Mango selector by `buildSelector`.
+ *
+ * This is the single authority on pushability - `buildSelector` imports it and refuses
+ * predicates that fail it, so the planner and the executor cannot drift apart and a
+ * predicate classified as pushed can never be silently dropped.
+ *
+ * @param {object} predicate The predicate AST node.
+ * @returns {boolean} True if the predicate is simple enough for pushdown.
+ */
+export declare function isPushablePredicate(predicate: any): boolean;
 /**
  * Creates a logical query plan from a list of Abstract Syntax Trees (ASTs) for a UNION query.
  * @param {Array<object>} astList The list of ASTs generated by the parser.
@@ -18,10 +35,12 @@ export declare function createPlan(astList: any): {
     aggregation: any;
     orderBy: any;
     limit: any;
+    offset: any;
 } | {
     type: string;
     selectPlans: any[];
     unionOps: any[];
     orderBy: any;
     limit: any;
+    offset: any;
 };