@haverstack/record-adapter-sqlite 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+
+To the extent possible under law, the Haverstack contributors have waived all
+copyright and related or neighboring rights to Haverstack. This work is
+published from the United States.
+
+https://creativecommons.org/publicdomain/zero/1.0/

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+import { TokenSession, StackRecord, RecordVersion, Permission, TypeId, StackQuery, QueryResult, FileId, RecordId, StackType, Association } from '@haverstack/core';
+import { StackRecordAdapter, AdapterCapabilities } from '@haverstack/core/adapter';
+import { StackTokenStore, TokenInfo } from '@haverstack/core/wire';
+
+/**
+ * Bearer-token storage backing @haverstack/core's StackTokenStore,
+ * implemented against its own file — deliberately separate from
+ * NativeSQLiteRecordAdapter's records database. The portable stack file
+ * is "your data, take it with you"; auth material shouldn't travel with
+ * it, and restoring a backup shouldn't resurrect revoked tokens. Server
+ * implementations wire these up as separate parts
+ * (`{ adapter, tokens }`), the same philosophy as combineAdapters().
+ *
+ * The actual createToken/lookupToken/listTokens/revokeToken logic lives
+ * in @haverstack/sqlite-shared's SharedTokenLogic, reached through the
+ * SqlExecutor interface.
+ */
+
+/** Conventional sibling path for a token store beside a stack's main .db file. */
+declare const defaultTokenStorePath: (dbPath: string) => string;
+type NativeTokenStoreOptions = {
+    /** Absolute path to the token store file. Created if it doesn't exist. */
+    path: string;
+    /** Bypass the storage-ownership lock check. See docs/spec/adapters.md § Concurrency & storage ownership. */
+    force?: boolean;
+};
+declare class NativeTokenStore implements StackTokenStore {
+    private readonly path;
+    private db;
+    private tokens;
+    private constructor();
+    /** Opens the token store, creating the file and schema if needed. */
+    static open(opts: NativeTokenStoreOptions): Promise<NativeTokenStore>;
+    createToken(principalId: string, opts?: {
+        onBehalfOf?: string;
+        label?: string;
+        expiresAt?: Date;
+    }): Promise<{
+        id: string;
+        token: string;
+    }>;
+    lookupToken(token: string): Promise<TokenSession | null>;
+    listTokens(): Promise<TokenInfo[]>;
+    revokeToken(id: string): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Haverstack — Native SQLite Record Adapter
+ * -------------------------------------------------------
+ * Implements StackRecordAdapter using node:sqlite (Node's built-in
+ * SQLite binding, Node >= 22.5). No native compilation, no node-gyp,
+ * no prebuilt binaries, and writes go straight to the file via normal
+ * SQLite journaling (WAL mode) — no whole-database rewrite per write,
+ * no in-memory copy of the whole store, real OS-level file locking.
+ * Full-text search uses FTS5.
+ *
+ * A stack file is owned by exactly one process at a time (see
+ * docs/spec/adapters.md § Concurrency & storage ownership). open()/initialize()
+ * acquire a PID-stamped lock file beside the database and reject if
+ * another live process already holds it; close() releases it.
+ *
+ * Token storage is a separate concern — see NativeTokenStore in this
+ * package, which implements @haverstack/core's StackTokenStore against
+ * its own file rather than this adapter's records database.
+ *
+ * This class itself is a thin node:sqlite binding: schema setup,
+ * pragmas, and the storage-ownership lock are genuinely engine-specific
+ * and live here. The actual StackRecordAdapter logic lives in
+ * @haverstack/sqlite-shared's SharedSqlRecordLogic, reached through the
+ * SqlExecutor interface (NativeSqliteExecutor here normalizes
+ * node:sqlite's spread-args run/get/all calls to it).
+ */
+
+type NativeRecordInitializeOptions = {
+    /** Absolute path to the .db file. Must not already exist. */
+    path: string;
+    /** IANA timezone string e.g. "America/New_York". Optional passthrough app metadata — no default. */
+    timezone?: string;
+    /** Entity ID of the stack owner. */
+    entityId: string;
+    /** Bypass the storage-ownership lock check. See NativeRecordOpenOptions.force. */
+    force?: boolean;
+};
+type NativeRecordOpenOptions = {
+    /** Absolute path to an existing .db file. */
+    path: string;
+    /**
+     * Open even if a lock file from another live process is present.
+     * Only needed if that process is gone but its PID was reused by
+     * something else (the automatic stale-lock check already reclaims
+     * locks whose owning process is no longer running).
+     */
+    force?: boolean;
+};
+declare class NativeSQLiteRecordAdapter implements StackRecordAdapter {
+    private readonly path;
+    readonly capabilities: AdapterCapabilities;
+    ownerEntityId: string;
+    timezone: string | undefined;
+    private db;
+    private record;
+    private constructor();
+    private wire;
+    /**
+     * Initialize a new stack database. Fails if the file already exists —
+     * use open() for existing databases.
+     */
+    static initialize(opts: NativeRecordInitializeOptions): Promise<NativeSQLiteRecordAdapter>;
+    /**
+     * Open an existing stack database. Fails if the file does not exist —
+     * use initialize() for new databases.
+     */
+    static open(opts: NativeRecordOpenOptions): Promise<NativeSQLiteRecordAdapter>;
+    createRecord(record: StackRecord): Promise<StackRecord>;
+    getRecord(id: string): Promise<StackRecord | null>;
+    patchContent(id: string, patch: Record<string, unknown | null>, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    }): Promise<StackRecord>;
+    deleteRecord(id: string, opts?: {
+        hard?: boolean;
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    }): Promise<void>;
+    undeleteRecord(id: string, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    }): Promise<StackRecord>;
+    setPermissions(id: string, permissions: Permission[], opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    }): Promise<void>;
+    restoreVersion(id: string, version: number, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    }): Promise<StackRecord>;
+    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: {
+        snapshot?: RecordVersion;
+    }): Promise<StackRecord>;
+    queryRecords(query: StackQuery): Promise<QueryResult>;
+    deleteUnreferencedAttachmentRecords(fileId: FileId, metadataTypeId: TypeId): Promise<RecordId[]>;
+    getVersions(id: string): Promise<RecordVersion[]>;
+    getVersion(id: string, version: number): Promise<RecordVersion | null>;
+    saveVersion(id: string, version: RecordVersion): Promise<void>;
+    saveType(type: StackType): Promise<void>;
+    getType(id: TypeId): Promise<StackType | null>;
+    listTypes(): Promise<StackType[]>;
+    associate(recordId: string, association: Association, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    }): Promise<void>;
+    dissociate(recordId: string, association: Association, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    }): Promise<void>;
+    /** Folds the WAL back into the main file — useful before copying/backing up the database. */
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+
+export { type NativeRecordInitializeOptions, type NativeRecordOpenOptions, NativeSQLiteRecordAdapter, NativeTokenStore, type NativeTokenStoreOptions, defaultTokenStorePath };