@docstack/client 0.0.1

package/lib/core/stack.d.ts

@@ -0,0 +1,497 @@
+import Class from "./class.js";
+import Domain from "./domain.js";
+import { Stack, StackOptions, AuthSessionProof, ClientCredentials, CachedClass, ClassModelPropagationStart, ClassModelPropagationComplete, CachedDomain, DomainModel } from "@docstack/shared";
+import { SystemDoc, Patch, ClassModel, Document, RelationDocument } from "@docstack/shared";
+import type { SelectAST, UnionAST } from "./query-engine/index.js";
+import { JobEngine } from "./job-engine/index.js";
+import { PolicyEngine } from "./policy-engine/index.js";
+import { CryptoEngine } from "./crypto-engine/index.js";
+export declare const BASE_SCHEMA: ClassModel["schema"];
+export declare const CLASS_SCHEMA: ClassModel["schema"];
+/**
+ * The core database engine for DocStack client applications.
+ *
+ * ClientStack provides a complete offline-first datastore built on PouchDB with:
+ * - Schema validation and class-based document modeling
+ * - SQL-like querying capabilities
+ * - Field-level encryption via {@link CryptoEngine}
+ * - Access control via {@link PolicyEngine}
+ * - Background job execution via {@link JobEngine}
+ *
+ * @example
+ * ```typescript
+ * // Create a new stack instance
+ * const stack = await ClientStack.create('my-app-db');
+ *
+ * // Authenticate a user
+ * const session = await stack.authenticate({ username: 'admin', password: 'secret' });
+ *
+ * // Query documents using SQL
+ * const { rows } = await stack.query('SELECT * FROM Task WHERE isComplete = false');
+ * ```
+ *
+ * @extends Stack
+ */
+declare class ClientStack extends Stack {
+    private static readonly CRYPTO_CONFIG_DOC_ID;
+    /**
+     * The underlying PouchDB database instance.
+     * Initialized asynchronously during stack creation.
+     *
+     * @example
+     * ```typescript
+     * // Access the raw PouchDB API for advanced operations
+     * const allDocs = await stack.db.allDocs({ include_docs: true });
+     * ```
+     */
+    db: PouchDB.Database<{}>;
+    /** The unique name identifier for this stack instance, derived from the connection string. */
+    name: string;
+    lastDocId: number;
+    /** The connection string used to create this stack. */
+    connection: string;
+    /** Configuration options provided during stack creation. */
+    options?: StackOptions;
+    /** The current application version string. */
+    appVersion: string;
+    /**
+     * In-memory cache for Class and Domain objects.
+     * Items are cached with a 15-minute TTL to improve performance.
+     */
+    cache: {
+        [className: string]: CachedClass | CachedDomain;
+    };
+    patchCount: number;
+    listeners: PouchDB.Core.Changes<{}>[];
+    modelWorker: Worker | null;
+    /**
+     * Engine for executing background jobs and scheduled tasks.
+     * Jobs are defined as documents and run in a sandboxed environment.
+     *
+     * @example
+     * ```typescript
+     * const run = await stack.jobEngine.executeJob('Job-CleanupOldData');
+     * console.log('Job completed:', run.status);
+     * ```
+     */
+    jobEngine: JobEngine;
+    /**
+     * Engine for enforcing read/write access control policies.
+     * Policies are evaluated based on user session and document content.
+     */
+    policyEngine: PolicyEngine;
+    /**
+     * Engine for field-level encryption and decryption.
+     * Handles key derivation (PBKDF2) and AES-GCM encryption.
+     */
+    cryptoEngine: CryptoEngine;
+    schemaVersion: string | undefined;
+    /**
+     * The current authenticated user session, if any.
+     * Contains session details, derived key, and document encryption key.
+     */
+    authSession?: AuthSessionProof;
+    private cryptoEngineDisabled;
+    private constructor();
+    private initialize;
+    /**
+     * Returns the underlying PouchDB database instance.
+     * @returns The PouchDB database
+     */
+    getDb(): PouchDB.Database<{}>;
+    /**
+     * Retrieves information about the database including document count and update sequence.
+     * @returns Database information object
+     */
+    getDbInfo(): Promise<PouchDB.Core.DatabaseInfo>;
+    /**
+     * Returns the name of the underlying PouchDB database.
+     * @returns The database name string
+     */
+    getDbName(): string;
+    /**
+     * Checks if the crypto engine was disabled during stack initialization.
+     * @returns `true` if encryption is disabled, `false` otherwise
+     */
+    isCryptoEngineDisabled(): boolean;
+    /**
+     * Sets the current authentication session.
+     * Called automatically by {@link authenticate}, but can be set manually for custom auth flows.
+     * @param proof - The authentication session proof containing session and encryption keys
+     */
+    setAuthSession(proof: AuthSessionProof): void;
+    /**
+     * Clears the current authentication session and removes the document encryption key.
+     * Call this when a user logs out.
+     */
+    clearAuthSession(): void;
+    /**
+     * Exports all documents from the database.
+     * Useful for debugging or creating backups.
+     * @returns All documents including their content
+     */
+    dump: () => Promise<PouchDB.Core.AllDocsResponse<{}>>;
+    private ensureDefaultPolicyForClass;
+    /**
+     * Creates and initializes a new ClientStack instance.
+     * This is the primary way to instantiate a stack - the constructor is private.
+     *
+     * @param conn - The connection string or database name
+     * @param options - Optional configuration including plugins, patches, and credentials
+     * @returns A fully initialized ClientStack instance
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const stack = await ClientStack.create('my-app-db');
+     *
+     * // With authentication
+     * const stack = await ClientStack.create('my-app-db', {
+     *     credentials: { username: 'admin', password: 'secret' }
+     * });
+     *
+     * // With custom patches
+     * const stack = await ClientStack.create('my-app-db', {
+     *     patches: [myCustomPatch]
+     * });
+     * ```
+     */
+    static create(conn: string, options?: StackOptions): Promise<ClientStack>;
+    /**
+     * Authenticates a user and establishes a session.
+     *
+     * This method:
+     * 1. Looks up the user by username
+     * 2. Executes the configured authentication job (e.g., password verification)
+     * 3. Creates a new session document
+     * 4. Sets up encryption keys for the session
+     *
+     * @param credentials - The user's login credentials containing username and password
+     * @returns The authentication session proof containing session info and encryption keys
+     * @throws Error if the user is not found or authentication fails
+     *
+     * @example
+     * ```typescript
+     * const proof = await stack.authenticate({
+     *     username: 'john.doe',
+     *     password: 'securePassword123'
+     * });
+     * console.log('Logged in as:', proof.session.username);
+     * ```
+     */
+    authenticate(credentials: ClientCredentials): Promise<AuthSessionProof>;
+    getLastDocId(): Promise<number>;
+    getSystem(): Promise<SystemDoc>;
+    private loadPatches;
+    applyPatch: (patch: Patch) => Promise<string>;
+    private applyPatches;
+    checkSystem(): Promise<void>;
+    setListeners: () => void;
+    /**
+     * @description Clears all listeners from the Stack
+     */
+    removeAllListeners: () => void;
+    /**
+     * @description When a class model propagation starts write the ~lock document to the database.
+     * It prevents any further modifications on the class data model
+     * @param event
+     */
+    onClassModelPropagationStart: (event: CustomEvent<ClassModelPropagationStart>) => void;
+    /**
+     * @description When a class model propagation comes to completion remove the corresponding
+     * ~lock from the database
+     * @param event
+     */
+    onClassModelPropagationComplete: (event: CustomEvent<ClassModelPropagationComplete>) => void;
+    /**
+     * @returns PouchDB.Core.Changes<{}>
+     */
+    onClassModelChanges: () => PouchDB.Core.Changes<{}>;
+    onClassLock: (className: string) => PouchDB.Core.Changes<{}>;
+    addClassLock: (className: string) => Promise<boolean>;
+    clearClassLock: (className: string) => Promise<boolean>;
+    onClassDoc: (className: string) => PouchDB.Core.Changes<{}>;
+    initdb(): Promise<this>;
+    private ensureCryptoConfigDocument;
+    private ensureCryptoMarkerEncryption;
+    private validateCryptoConfig;
+    /**
+     * Closes the stack and cleans up all resources.
+     * Removes event listeners and terminates background workers.
+     */
+    close: () => void;
+    /**
+     * Retrieves a Class instance by name.
+     * Results are cached for 15 minutes to improve performance.
+     *
+     * @param className - The name or ID of the class to retrieve
+     * @param fresh - If `true`, bypasses the cache and fetches from database
+     * @returns The Class instance, or `null` if not found
+     *
+     * @example
+     * ```typescript
+     * const taskClass = await stack.getClass('Task');
+     * if (taskClass) {
+     *     const tasks = await taskClass.getCards();
+     * }
+     * ```
+     */
+    getClass: (className: string, fresh?: boolean) => Promise<Class | null>;
+    /**
+     * Retrieves a Domain instance by name.
+     * Results are cached for 15 minutes to improve performance.
+     *
+     * @param domainName - The name or ID of the domain to retrieve
+     * @param fresh - If `true`, bypasses the cache and fetches from database
+     * @returns The Domain instance, or `null` if not found
+     */
+    getDomain: (domainName: string, fresh?: boolean) => Promise<Domain | null>;
+    initIndex(): Promise<void>;
+    /**
+     * Retrieves a single document by its ID.
+     *
+     * @typeParam T - The expected document type
+     * @param docId - The document ID to retrieve
+     * @returns The document, or `null` if not found
+     *
+     * @example
+     * ```typescript
+     * const task = await stack.getDocument<TaskDocument>('Task-123');
+     * if (task) {
+     *     console.log(task.title);
+     * }
+     * ```
+     */
+    getDocument<T extends Document>(docId: string): Promise<PouchDB.Core.ExistingDocument<T>>;
+    getDocRevision(docId: string): Promise<string>;
+    /**
+     * Finds multiple documents matching a PouchDB/Mango-style selector.
+     * Automatically filters to only active documents and applies access policies.
+     *
+     * @typeParam T - The expected document type
+     * @param selector - A PouchDB/Mango query selector
+     * @param fields - Optional list of fields to return
+     * @param skip - Number of documents to skip (for pagination)
+     * @param limit - Maximum number of documents to return
+     * @returns Object containing matching documents array
+     *
+     * @example
+     * ```typescript
+     * const result = await stack.findDocuments({
+     *     '~class': { $eq: 'Task' },
+     *     isComplete: { $eq: false }
+     * });
+     * console.log('Found tasks:', result.docs.length);
+     * ```
+     */
+    findDocuments: <T extends Document | RelationDocument = Document>(selector: {
+        [key: string]: any;
+    }, fields?: string[], skip?: number, limit?: number) => Promise<{
+        [key: string]: any;
+        docs: T[];
+    }>;
+    private processReadableDocument;
+    /**
+     * Finds a single document matching a selector.
+     * Convenience wrapper around {@link findDocuments} that returns the first match.
+     *
+     * @typeParam T - The expected document type
+     * @param selector - A PouchDB/Mango query selector
+     * @param fields - Optional list of fields to return
+     * @param skip - Number of documents to skip
+     * @param limit - Maximum number of documents to check
+     * @returns The first matching document, or `null` if none found
+     */
+    findDocument<T extends Document | RelationDocument = Document>(selector: any, fields?: any, skip?: any, limit?: any): Promise<T>;
+    getClassModel: (className: string) => Promise<ClassModel>;
+    getDomainModel: (domainName: string) => Promise<DomainModel>;
+    getClassModels: (conf?: {
+        listen?: boolean;
+        filter?: string[];
+        search?: string;
+    }) => Promise<{
+        list: ClassModel[];
+        listener?: undefined;
+    } | {
+        list: ClassModel[];
+        listener: PouchDB.Core.Changes<{}>;
+    }>;
+    getClasses: (conf: {
+        filter?: string[];
+        search?: string;
+    }) => Promise<Class[]>;
+    getDomainModels: (conf?: {
+        listen?: boolean;
+        filter?: string[];
+        search?: string;
+    }) => Promise<{
+        list: DomainModel[];
+        listener?: undefined;
+    } | {
+        list: DomainModel[];
+        listener: PouchDB.Core.Changes<{}>;
+    }>;
+    getDomains: (conf: {
+        filter?: string[];
+        search?: string;
+    }) => Promise<Domain[]>;
+    incrementLastDocId(): Promise<number>;
+    reset(): Promise<this>;
+    destroyDb(): Promise<boolean>;
+    static clear(conn: string): Promise<unknown>;
+    addClass: (classObj: Class) => Promise<ClassModel>;
+    addDomain: (domainObj: Domain) => Promise<DomainModel>;
+    updateClass: (classObj: Class) => Promise<Document>;
+    addDesignDocumentPKs: (className: string, pKs: string[], temp?: boolean) => Promise<string>;
+    prepareDoc(_id: string, type: string, params: {
+        [key: string]: string | number | boolean;
+    }, metaKey: "~class"): Document;
+    prepareDoc(_id: string, type: string, params: {
+        [key: string]: string | number | boolean;
+    }, metaKey: "~domain"): RelationDocument;
+    /**
+     * Creates or updates a single document in the database.
+     *
+     * If `docId` is provided and the document exists, it will be updated.
+     * If `docId` is `null`, a new ID will be auto-generated in the format `{type}-{incrementalId}`.
+     * Access policies are enforced before writing.
+     *
+     * @param docId - The document ID, or `null` to auto-generate
+     * @param type - The class name (e.g., 'Task', 'User')
+     * @param classObj - The Class instance or schema definition for validation
+     * @param params - The document data to save
+     * @returns The created or updated document
+     * @throws Error if policy check fails or document type conflicts
+     *
+     * @example
+     * ```typescript
+     * // Create with auto-generated ID
+     * const task = await stack.createDoc(null, 'Task', taskClass, {
+     *     title: 'New Task',
+     *     isComplete: false
+     * });
+     *
+     * // Update existing document
+     * await stack.createDoc('Task-123', 'Task', taskClass, {
+     *     title: 'Updated Title'
+     * });
+     * ```
+     */
+    createDoc: (docId: string | null, type: string, classObj: Class | ClassModel["schema"], params: {}) => Promise<Document>;
+    /**
+     * Creates or updates multiple documents in a single batch operation.
+     * More efficient than calling {@link createDoc} multiple times.
+     *
+     * @param docs - Array of document specifications with optional docId and params
+     * @param type - The class name for all documents
+     * @param classObj - The Class instance or schema definition for validation
+     * @returns Array of created or updated documents
+     * @throws Error if policy check fails for any document
+     *
+     * @example
+     * ```typescript
+     * const tasks = await stack.createDocs([
+     *     { docId: null, params: { title: 'Task 1' } },
+     *     { docId: null, params: { title: 'Task 2' } },
+     *     { docId: 'Task-existing', params: { title: 'Updated' } }
+     * ], 'Task', taskClass);
+     * ```
+     */
+    createDocs: (docs: {
+        docId: string | null;
+        params: {};
+    }[], type: string, classObj: Class | ClassModel["schema"]) => Promise<Document[]>;
+    /**
+     * Creates a relation document linking two entities via a Domain.
+     * Relation documents represent relationships between documents (e.g., 1:N, N:N).
+     *
+     * @param docId - The relation document ID, or `null` to auto-generate
+     * @param relationName - A descriptive name for this relation instance
+     * @param domainObj - The Domain defining the relationship type
+     * @param params - The relation parameters including source and target references
+     * @returns The created relation document, or `null` on error
+     *
+     * @example
+     * ```typescript
+     * const relation = await stack.createRelationDoc(
+     *     null,
+     *     'ProjectTask',
+     *     projectTaskDomain,
+     *     {
+     *         sourceClass: 'Project',
+     *         targetClass: 'Task',
+     *         sourceId: 'Project-1',
+     *         targetId: 'Task-42'
+     *     }
+     * );
+     * ```
+     */
+    createRelationDoc: (docId: string | null, relationName: string, domainObj: Domain, params: {
+        sourceClass: string;
+        targetClass: string;
+        sourceId: string;
+        targetId: string;
+    }) => Promise<RelationDocument | null>;
+    /**
+     * Creates multiple relation documents in a single batch operation.
+     * More efficient than calling {@link createRelationDoc} multiple times.
+     *
+     * @param docs - Array of relation specifications
+     * @param relationName - A descriptive name for these relations
+     * @param domainObj - The Domain defining the relationship type
+     * @returns Array of created relation documents
+     *
+     * @example
+     * ```typescript
+     * const relations = await stack.createRelationDocs([
+     *     { docId: null, params: { sourceClass: 'Project', targetClass: 'Task', sourceId: 'Project-1', targetId: 'Task-1' } },
+     *     { docId: null, params: { sourceClass: 'Project', targetClass: 'Task', sourceId: 'Project-1', targetId: 'Task-2' } }
+     * ], 'ProjectTasks', projectTaskDomain);
+     * ```
+     */
+    createRelationDocs: (docs: {
+        docId: string | null;
+        params: {
+            sourceClass: string;
+            targetClass: string;
+            sourceId: string;
+            targetId: string;
+        };
+    }[], relationName: string, domainObj: Domain) => Promise<RelationDocument[]>;
+    /**
+     * Sets the active param of a document to false
+     * @param _id
+     * @returns Promise<boolean>
+     */
+    deleteDocument: (_id: string) => Promise<boolean>;
+    /**
+     * Executes a SQL query against the local database.
+     * Supports SELECT, JOIN, WHERE, ORDER BY, GROUP BY, and UNION operations.
+     *
+     * @param sql - The SQL query string
+     * @param params - Optional query parameters for prepared statements
+     * @returns Object containing result rows and the parsed AST
+     *
+     * @example
+     * ```typescript
+     * // Simple select
+     * const { rows } = await stack.query('SELECT * FROM Task WHERE isComplete = false');
+     *
+     * // Join with ordering
+     * const { rows } = await stack.query(`
+     *     SELECT t.title, u.username AS assignee
+     *     FROM Task AS t
+     *     JOIN User AS u ON u._id = t.assigneeId
+     *     ORDER BY t.createdAt DESC
+     * `);
+     *
+     * // With parameters
+     * const { rows } = await stack.query('SELECT * FROM Task WHERE priority = ?', 'high');
+     * ```
+     */
+    query: (sql: string, ...params: any[]) => Promise<{
+        rows: any;
+        ast: (SelectAST | UnionAST)[];
+    }>;
+}
+export default ClientStack;