@async/db 0.2.0

package/dist/integrations/kv.d.ts

@@ -0,0 +1,69 @@
+type KvClient = {
+    get(key: string): string | null | undefined | Promise<string | null | undefined>;
+    set(key: string, value: string): unknown | Promise<unknown>;
+    [key: string]: unknown;
+};
+type KvStoreOptions = {
+    client?: KvClient | null;
+    prefix?: string;
+    close?: boolean | ((client: KvClient | null | undefined) => unknown | Promise<unknown>);
+};
+type RuntimeConfig = Record<string, unknown>;
+type RuntimeResource = {
+    name: string;
+    [key: string]: unknown;
+};
+type StoreFactoryContext = {
+    config: RuntimeConfig;
+    storeName: string;
+};
+type ResourceWriteOperation<T> = () => T | Promise<T>;
+export declare const kvStoreCapabilities: {
+    writable: boolean;
+    persistence: string;
+    atomicity: string;
+    liveEvents: boolean;
+    staticExport: boolean;
+    production: string;
+};
+export declare function kvStore(options?: KvStoreOptions): ({ config, storeName }: StoreFactoryContext) => {
+    name: string;
+    capabilities: {
+        writable: boolean;
+        persistence: string;
+        atomicity: string;
+        liveEvents: boolean;
+        staticExport: boolean;
+        production: string;
+    };
+    hydrate(resources: RuntimeResource[]): Promise<void>;
+    readResource(resource: RuntimeResource, fallback: unknown): Promise<unknown>;
+    writeResource(resource: RuntimeResource, value: unknown): Promise<void>;
+    withResourceWrite<T>(resource: RuntimeResource, operation: ResourceWriteOperation<T>): Promise<T>;
+    close(): Promise<void>;
+};
+export declare function redisStore(options?: KvStoreOptions): ({ config, storeName }: StoreFactoryContext) => {
+    name: string;
+    capabilities: {
+        writable: boolean;
+        persistence: string;
+        atomicity: string;
+        liveEvents: boolean;
+        staticExport: boolean;
+        production: string;
+    };
+    hydrate(resources: RuntimeResource[]): Promise<void>;
+    readResource(resource: RuntimeResource, fallback: unknown): Promise<unknown>;
+    writeResource(resource: RuntimeResource, value: unknown): Promise<void>;
+    withResourceWrite<T>(resource: RuntimeResource, operation: ResourceWriteOperation<T>): Promise<T>;
+    close(): Promise<void>;
+};
+export declare const redisStoreCapabilities: {
+    writable: boolean;
+    persistence: string;
+    atomicity: string;
+    liveEvents: boolean;
+    staticExport: boolean;
+    production: string;
+};
+export {};

package/dist/integrations/kv.js

@@ -0,0 +1,69 @@
+import { dbError } from '../errors.js';
+import { closeInjectedClient, createResourceWriteQueue, envelopeForResource, hydrateJsonResourceStore, parseJsonEnvelope, } from '../features/storage/resource-json.js';
+export const kvStoreCapabilities = {
+    writable: true,
+    persistence: 'kv',
+    atomicity: 'resource',
+    liveEvents: true,
+    staticExport: false,
+    production: 'small-app',
+};
+export function kvStore(options = {}) {
+    const { client, prefix = 'async-db:', close = false, } = options;
+    const withQueuedWrite = createResourceWriteQueue();
+    return ({ config, storeName }) => {
+        assertKvClient(client, storeName);
+        function keyFor(resource) {
+            return `${prefix}${encodeURIComponent(resource.name)}`;
+        }
+        async function readEnvelope(resource) {
+            return parseJsonEnvelope(await client.get(keyFor(resource)), storeName);
+        }
+        async function writeEnvelope(resource, envelope) {
+            await client.set(keyFor(resource), JSON.stringify(envelope));
+        }
+        return {
+            name: storeName,
+            capabilities: kvStoreCapabilities,
+            async hydrate(resources) {
+                for (const resource of resources) {
+                    await hydrateJsonResourceStore({
+                        config,
+                        resource,
+                        readEnvelope,
+                        writeEnvelope,
+                    });
+                }
+            },
+            async readResource(resource, fallback) {
+                const envelope = await readEnvelope(resource);
+                return envelope ? envelope.value : fallback;
+            },
+            async writeResource(resource, value) {
+                await writeEnvelope(resource, envelopeForResource(resource, value));
+            },
+            withResourceWrite(resource, operation) {
+                return withQueuedWrite(keyFor(resource), operation);
+            },
+            close() {
+                return closeInjectedClient(client, close);
+            },
+        };
+    };
+}
+export function redisStore(options = {}) {
+    return kvStore(options);
+}
+export const redisStoreCapabilities = kvStoreCapabilities;
+function assertKvClient(client, storeName) {
+    if (client && typeof client.get === 'function' && typeof client.set === 'function') {
+        return;
+    }
+    throw dbError('KV_STORE_CLIENT_REQUIRED', `KV store "${storeName}" requires an injected client with get(key) and set(key, value).`, {
+        status: 500,
+        hint: 'Pass a Redis-like, edge KV, or compatible object to kvStore({ client }).',
+        details: {
+            store: storeName,
+        },
+    });
+}

package/dist/integrations/postgres.d.ts

@@ -0,0 +1,52 @@
+type PostgresQueryResult = {
+    rows?: Array<Record<string, unknown>>;
+};
+type PostgresClient = {
+    query(sql: string, params?: unknown[]): PostgresQueryResult | Promise<PostgresQueryResult>;
+    [key: string]: unknown;
+};
+type PostgresStoreOptions = {
+    client?: PostgresClient | null;
+    schema?: string;
+    table?: string;
+    namespace?: string;
+    migrate?: boolean;
+    close?: boolean | ((client: PostgresClient | null | undefined) => unknown | Promise<unknown>);
+};
+type RuntimeConfig = Record<string, unknown>;
+type RuntimeResource = {
+    name: string;
+    kind?: string;
+    dataHash?: string | null;
+    [key: string]: unknown;
+};
+type StoreFactoryContext = {
+    config: RuntimeConfig;
+    storeName: string;
+};
+type ResourceWriteOperation<T> = () => T | Promise<T>;
+export declare const postgresStoreCapabilities: {
+    writable: boolean;
+    persistence: string;
+    atomicity: string;
+    liveEvents: boolean;
+    staticExport: boolean;
+    production: string;
+};
+export declare function postgresStore(options?: PostgresStoreOptions): ({ config, storeName }: StoreFactoryContext) => {
+    name: string;
+    capabilities: {
+        writable: boolean;
+        persistence: string;
+        atomicity: string;
+        liveEvents: boolean;
+        staticExport: boolean;
+        production: string;
+    };
+    hydrate(resources: RuntimeResource[]): Promise<void>;
+    readResource(resource: RuntimeResource, fallback: unknown): Promise<unknown>;
+    writeResource(resource: RuntimeResource, value: unknown): Promise<void>;
+    withResourceWrite<T>(resource: RuntimeResource, operation: ResourceWriteOperation<T>): Promise<T>;
+    close(): Promise<void>;
+};
+export {};

package/dist/integrations/postgres.js

@@ -0,0 +1,113 @@
+import { dbError } from '../errors.js';
+import { createResourceWriteQueue, hydrateJsonResourceStore, closeInjectedClient, } from '../features/storage/resource-json.js';
+export const postgresStoreCapabilities = {
+    writable: true,
+    persistence: 'postgres',
+    atomicity: 'resource',
+    liveEvents: true,
+    staticExport: false,
+    production: 'small-app',
+};
+export function postgresStore(options = {}) {
+    const { client, schema = 'public', table = '_async_db_resources', namespace = 'default', migrate = true, close = false, } = options;
+    const withQueuedWrite = createResourceWriteQueue();
+    let migrated = false;
+    return ({ config, storeName }) => {
+        assertPostgresClient(client, storeName);
+        const qualifiedTable = `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+        async function ensureMigrated() {
+            if (!migrate || migrated) {
+                return;
+            }
+            if (schema !== 'public') {
+                await client.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(schema)}`);
+            }
+            await client.query(`CREATE TABLE IF NOT EXISTS ${qualifiedTable} (
+  namespace TEXT NOT NULL,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  source_hash TEXT,
+  value JSONB NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (namespace, name)
+)`);
+            migrated = true;
+        }
+        async function readEnvelope(resource) {
+            await ensureMigrated();
+            const result = await client.query(`SELECT kind, source_hash, value FROM ${qualifiedTable} WHERE namespace = $1 AND name = $2`, [namespace, resource.name]);
+            const row = result?.rows?.[0];
+            if (!row) {
+                return null;
+            }
+            return {
+                kind: String(row.kind),
+                sourceHash: typeof row.source_hash === 'string' ? row.source_hash : null,
+                value: typeof row.value === 'string' ? JSON.parse(row.value) : row.value,
+            };
+        }
+        async function writeEnvelope(resource, envelope) {
+            await ensureMigrated();
+            await client.query(`INSERT INTO ${qualifiedTable} (namespace, name, kind, source_hash, value, updated_at)
+VALUES ($1, $2, $3, $4, $5, CURRENT_TIMESTAMP)
+ON CONFLICT (namespace, name) DO UPDATE SET
+  kind = EXCLUDED.kind,
+  source_hash = EXCLUDED.source_hash,
+  value = EXCLUDED.value,
+  updated_at = CURRENT_TIMESTAMP`, [
+                namespace,
+                resource.name,
+                envelope.kind,
+                envelope.sourceHash ?? null,
+                JSON.stringify(envelope.value),
+            ]);
+        }
+        return {
+            name: storeName,
+            capabilities: postgresStoreCapabilities,
+            async hydrate(resources) {
+                await ensureMigrated();
+                for (const resource of resources) {
+                    await hydrateJsonResourceStore({
+                        config,
+                        resource,
+                        readEnvelope,
+                        writeEnvelope,
+                    });
+                }
+            },
+            async readResource(resource, fallback) {
+                const envelope = await readEnvelope(resource);
+                return envelope ? envelope.value : fallback;
+            },
+            async writeResource(resource, value) {
+                await writeEnvelope(resource, {
+                    kind: resource.kind,
+                    sourceHash: resource.dataHash ?? null,
+                    value,
+                });
+            },
+            withResourceWrite(resource, operation) {
+                return withQueuedWrite(`${namespace}:${resource.name}`, operation);
+            },
+            close() {
+                return closeInjectedClient(client, close);
+            },
+        };
+    };
+}
+function assertPostgresClient(client, storeName) {
+    if (client && typeof client.query === 'function') {
+        return;
+    }
+    throw dbError('POSTGRES_STORE_CLIENT_REQUIRED', `Postgres store "${storeName}" requires an injected client with query(sql, params).`, {
+        status: 500,
+        hint: 'Pass a pg Pool, pg Client, or compatible object to postgresStore({ client }).',
+        details: {
+            store: storeName,
+        },
+    });
+}
+function quoteIdentifier(value) {
+    return `"${String(value).replaceAll('"', '""')}"`;
+}

package/dist/integrations/sqlite.d.ts

@@ -0,0 +1,112 @@
+import type { SchemaField } from '../features/schema/fields.js';
+type SqliteValue = string | number | bigint | Buffer | null;
+type SqliteRow = Record<string, SqliteValue>;
+type SqliteRunResult = {
+    changes: number;
+    lastInsertRowid?: number | bigint;
+};
+type SqliteStatement = {
+    get(...values: unknown[]): SqliteRow | undefined;
+    all(...values: unknown[]): SqliteRow[];
+    run(...values: unknown[]): SqliteRunResult;
+};
+type SqliteDatabase = {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    close(): void;
+};
+type SqliteConfig = {
+    cwd: string;
+    stateDir: string;
+    defaults?: {
+        applyOnCreate?: boolean;
+        applyOnSafeMigration?: boolean;
+    };
+    [key: string]: unknown;
+};
+type SqliteResource = {
+    name: string;
+    kind: 'collection' | 'document' | string;
+    idField?: string;
+    fields: Record<string, SchemaField>;
+    dataHash?: string | null;
+    [key: string]: unknown;
+};
+type SqliteProject = {
+    resources: SqliteResource[];
+};
+type OpenSqliteOptions = Record<string, unknown> & {
+    project?: SqliteProject;
+    storage?: {
+        file?: string;
+        [key: string]: unknown;
+    };
+    file?: string;
+};
+type SqliteStoreOptions = {
+    file?: string;
+};
+type StoreContext = {
+    config: SqliteConfig;
+    storeName: string;
+};
+type StoreAdapter = {
+    name: string;
+    capabilities: typeof sqliteStoreCapabilities;
+    statePath(): string | undefined;
+    hydrate(resources: SqliteResource[]): Promise<void>;
+    readResource(resource: SqliteResource, fallback: unknown): unknown;
+    writeResource(resource: SqliteResource, value: unknown): void;
+    withResourceWrite<T>(resource: SqliteResource, operation: () => T | Promise<T>): Promise<T>;
+    close(): void;
+};
+type ResourceKind = 'collection' | 'document';
+export declare function openSqliteDb(options?: OpenSqliteOptions): Promise<SqliteDb>;
+export declare function sqliteStore(options?: SqliteStoreOptions): (context: StoreContext) => StoreAdapter;
+export declare const sqliteStoreCapabilities: {
+    writable: boolean;
+    persistence: string;
+    atomicity: string;
+    liveEvents: boolean;
+    staticExport: boolean;
+    production: string;
+};
+export declare function migrateSqliteDb(database: SqliteDatabase, resources: SqliteResource[]): void;
+export declare class SqliteDb {
+    config: SqliteConfig;
+    resources: Map<string, SqliteResource>;
+    database: SqliteDatabase;
+    constructor(config: SqliteConfig, resources: SqliteResource[], database: SqliteDatabase);
+    collection(name: string): SqliteDbCollection;
+    document(name: string): SqliteDbDocument;
+    resourceNames(): string[];
+    close(): void;
+    requireResource(name: string, kind: ResourceKind): SqliteResource;
+}
+export declare class SqliteDbCollection {
+    config: SqliteConfig;
+    resource: SqliteResource;
+    database: SqliteDatabase;
+    table: string;
+    constructor(config: SqliteConfig, resource: SqliteResource, database: SqliteDatabase);
+    all(): Promise<Record<string, unknown>[]>;
+    get(id: unknown): Promise<Record<string, unknown> | null>;
+    exists(id: unknown): Promise<boolean>;
+    create(record: unknown): Promise<Record<string, unknown>>;
+    update(id: unknown, patch: unknown): Promise<Record<string, unknown> | null>;
+    patch(id: unknown, patch: unknown): Promise<Record<string, unknown> | null>;
+    delete(id: unknown): Promise<boolean>;
+    nextId(): Promise<string>;
+}
+export declare class SqliteDbDocument {
+    config: SqliteConfig;
+    resource: SqliteResource;
+    database: SqliteDatabase;
+    constructor(config: SqliteConfig, resource: SqliteResource, database: SqliteDatabase);
+    all(): Promise<Record<string, unknown>>;
+    get(pointer?: string): Promise<unknown>;
+    put(value: unknown): Promise<Record<string, unknown>>;
+    set(pointer: string, value: unknown): Promise<unknown>;
+    update(patch: unknown): Promise<Record<string, unknown>>;
+}
+export {};