@haverstack/record-adapter-do-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,134 @@
+import { StackRecord, RecordVersion, ActorOptions, Permission, TypeId, StackQuery, QueryResult, FileId, StackType, Association } from '@haverstack/core';
+import { StackRecordAdapter, AdapterCapabilities } from '@haverstack/core/adapter';
+import { SqlExecutor } from '@haverstack/sqlite-shared/record';
+
+/**
+ * Normalizes a Durable Object's ctx.storage.sql to SqlExecutor.
+ *
+ * Two things don't map onto node:sqlite's shape the way the rest of this
+ * interface does:
+ *
+ * - There is no get/all/run split — sql.exec() always returns a cursor.
+ *   get()/all() read it via .toArray(); run() reads .rowsWritten for the
+ *   affected-row count run()'s contract promises.
+ * - Raw BEGIN/COMMIT/ROLLBACK are rejected outright by DO SQLite (verified
+ *   against the real Workers runtime, not assumed) — its storage has no
+ *   notion of a transaction left open across separate exec() calls, and
+ *   each statement auto-commits the instant it runs, so no-op'ing those
+ *   three strings would silently break atomicity, not preserve it. The
+ *   platform's real primitive is ctx.storage.transactionSync(fn), which
+ *   SqlExecutor.transaction() reaches directly — see docs/spec/adapters.md
+ *   § Concurrency & storage ownership.
+ */
+declare class DurableObjectSqliteExecutor implements SqlExecutor {
+    private readonly storage;
+    constructor(storage: DurableObjectStorage);
+    private get sql();
+    exec(sql: string): void;
+    run(sql: string, params?: readonly unknown[]): number;
+    get<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): T | undefined;
+    all<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): T[];
+    transaction<T>(fn: () => T): T;
+}
+
+/**
+ * Haverstack — Durable Object SQLite Record Adapter
+ * -------------------------------------------------------
+ * Implements StackRecordAdapter over a Cloudflare Durable Object's SQLite
+ * storage (ctx.storage.sql). Full-text search uses FTS5, same as
+ * record-adapter-sqlite — DO's SQLite build ships it.
+ *
+ * Ownership and durability come from the platform, not from anything this
+ * class does: a Durable Object id maps to exactly one running instance,
+ * so there is no separate lock file the way record-adapter-sqlite needs
+ * one for real files (see docs/spec/adapters.md § Concurrency & storage
+ * ownership) — the DO *is* the lock. There is likewise no persist/flush
+ * step: every write through ctx.storage.sql is durable by the time the
+ * call returns, so flush()/close() are no-ops kept only to satisfy the
+ * optional StackRecordAdapter methods.
+ *
+ * This class itself is a thin binding: schema setup and the one piece of
+ * genuinely engine-specific wiring — SqlExecutor.transaction() reaching
+ * ctx.storage.transactionSync() instead of raw SQL BEGIN/COMMIT/ROLLBACK,
+ * which DO SQLite rejects outright — live here (see executor.ts). The
+ * actual StackRecordAdapter logic lives in @haverstack/sqlite-shared's
+ * SharedSqlRecordLogic, exactly as it does for record-adapter-sqlite.
+ */
+
+type DoRecordCreateOptions = {
+    /** Entity ID of the stack owner. Ignored if the DO's storage already has a config record. */
+    entityId: string;
+    /** IANA timezone string e.g. "America/New_York". Optional passthrough app metadata — no default. */
+    timezone?: string;
+};
+declare class DoSQLiteRecordAdapter implements StackRecordAdapter {
+    private readonly exec;
+    readonly capabilities: AdapterCapabilities;
+    ownerEntityId: string;
+    timezone: string | undefined;
+    private readonly record;
+    private constructor();
+    /**
+     * Create (or reattach to) the adapter for a DO instance. There is no
+     * initialize()/open() split the way file-based adapters need one: a DO
+     * id either already has a config record (a previous call created it —
+     * reattach, opts.entityId/timezone ignored in favor of what's stored)
+     * or it doesn't (first call — opts.entityId/timezone become the config).
+     * Schema DDL is `CREATE TABLE IF NOT EXISTS`, so running it every call
+     * is idempotent and cheap.
+     */
+    static create(storage: DurableObjectStorage, opts: DoRecordCreateOptions): Promise<DoSQLiteRecordAdapter>;
+    createRecord(record: StackRecord): Promise<StackRecord>;
+    getRecord(id: string): Promise<StackRecord | null>;
+    patchContent(id: string, patch: Record<string, unknown | null>, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    deleteRecord(id: string, opts?: {
+        hard?: boolean;
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord | null>;
+    undeleteRecord(id: string, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    setPermissions(id: string, permissions: Permission[], opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    setUnlisted(id: string, unlisted: boolean, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    restoreVersion(id: string, version: number, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    queryRecords(query: StackQuery): Promise<QueryResult>;
+    deleteUnreferencedAttachmentRecords(fileId: FileId, metadataTypeId: TypeId): Promise<StackRecord[]>;
+    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;
+    } & ActorOptions): Promise<StackRecord>;
+    dissociate(recordId: string, association: Association, opts?: {
+        expectedVersion?: number;
+        snapshot?: RecordVersion;
+    } & ActorOptions): Promise<StackRecord>;
+    /** No-op: every write through ctx.storage.sql is already durable. */
+    flush(): Promise<void>;
+    /** No-op: no lock file, no connection to release — the DO's own lifecycle governs storage. */
+    close(): Promise<void>;
+}
+
+export { type DoRecordCreateOptions, DoSQLiteRecordAdapter, DurableObjectSqliteExecutor };