@evumi/berth 0.0.9 → 0.0.10

package/dist/esm/documents.js

@@ -0,0 +1,180 @@
+import { sha256 } from './sha256.js';
+import { DocumentError, entries, invalid, jsonText, MAX_DOCUMENT_BYTES, validateJSON } from './documents/json.js';
+import { compileFilter, compileSort, path, sortFields, typeSQL, valueSQL } from './documents/query.js';
+export { DocumentError, MAX_DOCUMENT_BYTES };
+const TABLE = '"_berth_documents"';
+const SCHEMA = `CREATE TABLE IF NOT EXISTS ${TABLE} (
+  collection TEXT NOT NULL, id TEXT NOT NULL,
+  data TEXT NOT NULL CHECK (
+    json_valid(data) AND json_type(data) = 'object' AND
+    json_type(data, '$._id') IS 'text' AND json_extract(data, '$._id') = id AND
+    length(CAST(data AS BLOB)) <= ${MAX_DOCUMENT_BYTES}
+  ), PRIMARY KEY (collection, id)
+)`;
+/** A collection is a query namespace, not an authorization boundary. Give each
+ * project/environment its own database credential or local file. No retry occurs. */
+export function createDocumentStore(client) {
+    const execute = async (sql, args = []) => {
+        try {
+            return (await client.execute({ sql, args })).rows;
+        }
+        catch {
+            throw new DocumentError('database_error', 'Document database operation failed; a write outcome may be unknown. No retry was attempted.');
+        }
+    };
+    let initialization;
+    const ready = () => initialization ??= execute(SCHEMA).then(() => { });
+    const run = async (sql, args = []) => { await ready(); return execute(sql, args); };
+    return { ready, collection(name) {
+            if (typeof name !== 'string' || !name.length || name.length > 128 || name.includes('\0'))
+                invalid('Collection name must contain 1 to 128 characters and no NUL');
+            return new DocumentCollection(name, run);
+        } };
+}
+function filterSQL(filter) { validateJSON(filter); return compileFilter(filter); }
+function decode(row) {
+    try {
+        if (typeof row.data !== 'string' || typeof row.id !== 'string')
+            throw new Error();
+        const doc = JSON.parse(row.data);
+        validateJSON(doc);
+        if (doc === null || Array.isArray(doc) || typeof doc !== 'object' || doc._id !== row.id)
+            throw new Error();
+        return doc;
+    }
+    catch {
+        throw new DocumentError('invalid_data', 'Stored document is invalid');
+    }
+}
+export class DocumentCursor {
+    collection;
+    execute;
+    filter;
+    order;
+    take;
+    offset;
+    constructor(collection, execute, filter, order = 'id ASC', take = 100, offset = 0) {
+        this.collection = collection;
+        this.execute = execute;
+        this.filter = filter;
+        this.order = order;
+        this.take = take;
+        this.offset = offset;
+    }
+    sort(sort) {
+        return new DocumentCursor(this.collection, this.execute, this.filter, compileSort(sort), this.take, this.offset);
+    }
+    limit(n) {
+        if (!Number.isInteger(n) || n < 0 || n > 1000)
+            invalid('Limit must be an integer from 0 to 1000');
+        return new DocumentCursor(this.collection, this.execute, this.filter, this.order, n, this.offset);
+    }
+    skip(n) {
+        if (!Number.isSafeInteger(n) || n < 0 || n > 1_000_000)
+            invalid('Skip must be an integer from 0 to 1000000');
+        return new DocumentCursor(this.collection, this.execute, this.filter, this.order, this.take, n);
+    }
+    async toArray() {
+        const rows = await this.execute(`SELECT id, data FROM ${TABLE} WHERE collection = ? AND (${this.filter.sql}) ORDER BY ${this.order} LIMIT ? OFFSET ?`, [this.collection, ...this.filter.args, this.take, this.offset]);
+        return rows.map(row => decode(row));
+    }
+}
+export class DocumentCollection {
+    name;
+    execute;
+    constructor(name, execute) {
+        this.name = name;
+        this.execute = execute;
+    }
+    async insertOne(document) {
+        const input = entries(document, 'document');
+        validateJSON(document);
+        const supplied = input.find(([key]) => key === '_id');
+        const id = supplied ? supplied[1] : globalThis.crypto.randomUUID();
+        if (typeof id !== 'string' || !id.length || id.length > 256 || id.includes('\0'))
+            invalid('_id must contain 1 to 256 characters and no NUL');
+        const data = Object.fromEntries(input);
+        data._id = id;
+        await this.execute(`INSERT INTO ${TABLE} (collection, id, data) VALUES (?, ?, ?)`, [this.name, id, jsonText(data)]);
+        return { insertedId: id };
+    }
+    find(filter = {}) { return new DocumentCursor(this.name, this.execute, filterSQL(filter)); }
+    async findOne(filter = {}) { return (await this.find(filter).limit(1).toArray())[0] ?? null; }
+    async countDocuments(filter = {}) {
+        const f = filterSQL(filter);
+        const rows = await this.execute(`SELECT count(*) AS count FROM ${TABLE} WHERE collection = ? AND (${f.sql})`, [this.name, ...f.args]);
+        const n = Number(rows[0]?.count);
+        if (!Number.isSafeInteger(n) || n < 0)
+            throw new DocumentError('invalid_data', 'Document count exceeds the supported range');
+        return n;
+    }
+    async deleteOne(filter) {
+        const f = filterSQL(filter);
+        const rows = await this.execute(`DELETE FROM ${TABLE} WHERE collection = ? AND id = (SELECT id FROM ${TABLE} WHERE collection = ? AND (${f.sql}) ORDER BY id LIMIT 1) RETURNING id`, [this.name, this.name, ...f.args]);
+        return { deletedCount: rows.length };
+    }
+    async updateOne(filter, update) {
+        const f = filterSQL(filter), u = compileUpdate(update);
+        const rows = await this.execute(`UPDATE ${TABLE} SET data = ${u.sql} WHERE collection = ? AND id = (SELECT id FROM ${TABLE} WHERE collection = ? AND (${f.sql}) ORDER BY id LIMIT 1) RETURNING id`, [...u.args, this.name, this.name, ...f.args]);
+        return { matchedCount: rows.length };
+    }
+    /** Indexes cover all collections, with collection as the leading key.
+     * Identical specs share one index. Queries still bind the collection. */
+    async createIndex(spec) {
+        const fields = sortFields(spec);
+        if (!fields.some(([field]) => field === '_id'))
+            fields.push(['_id', 1]);
+        const digest = Array.from(sha256(new TextEncoder().encode(JSON.stringify(fields))), b => b.toString(16).padStart(2, '0')).join('').slice(0, 32);
+        const name = `_berth_docs_idx_${digest}`;
+        const expressions = fields.map(([field, order]) => `${valueSQL(field)} ${order === 1 ? 'ASC' : 'DESC'}`);
+        await this.execute(`CREATE INDEX IF NOT EXISTS "${name}" ON ${TABLE} (collection, ${expressions.join(', ')})`);
+        return name;
+    }
+}
+function compileUpdate(update) {
+    validateJSON(update);
+    const paths = [], guards = [], guardArgs = [], args = [];
+    let expression = 'data';
+    for (const [operator, value] of entries(update, 'update')) {
+        if (!['$set', '$unset', '$inc'].includes(operator))
+            invalid('Unsupported update operator');
+        for (const [field, operand] of entries(value, 'update fields')) {
+            const jsonPath = path(field);
+            if (field === '_id' || field.startsWith('_id.'))
+                invalid('_id is immutable');
+            if (paths.some(p => p === field || p.startsWith(field + '.') || field.startsWith(p + '.')))
+                invalid('Update paths must not overlap');
+            paths.push(field);
+            if (paths.length > 32)
+                invalid('Update exceeds 32 fields');
+            const segments = field.split('.');
+            for (let i = 1; i < segments.length; i++) {
+                const parent = typeSQL(segments.slice(0, i).join('.'));
+                guards.push(`(${parent} IS NULL OR ${parent} = 'object')`);
+            }
+            if (operator === '$set') {
+                expression = `json_set(${expression}, '${jsonPath}', json(?))`;
+                args.push(jsonText(operand));
+            }
+            else if (operator === '$unset') {
+                if (operand !== true && operand !== 1)
+                    invalid('$unset values must be true or 1');
+                expression = `json_remove(${expression}, '${jsonPath}')`;
+            }
+            else {
+                if (typeof operand !== 'number' || !Number.isFinite(operand))
+                    invalid('$inc requires a finite number');
+                const type = typeSQL(field), current = valueSQL(field);
+                guards.push(`(${type} IS NULL OR ${type} IN ('integer', 'real'))`);
+                guards.push(`(coalesce(${current}, 0) + ? BETWEEN ? AND ?)`);
+                guardArgs.push(operand, -Number.MAX_VALUE, Number.MAX_VALUE);
+                expression = `json_set(${expression}, '${jsonPath}', coalesce(${current}, 0) + ?)`;
+                args.push(operand);
+            }
+        }
+    }
+    if (!paths.length)
+        invalid('Update must change at least one field');
+    // A bad selected target aborts this one statement, including all other fields.
+    return { sql: guards.length ? `CASE WHEN ${guards.join(' AND ')} THEN ${expression} ELSE json('invalid document update') END` : expression, args: [...guardArgs, ...args] };
+}

package/dist/esm/worker.d.ts

@@ -0,0 +1,25 @@
+/** State lives only in one running project/environment process and is lost on restart. */
+export interface WorkerRuntime {
+    readonly state: Map<string, unknown>;
+    readonly startedAt: Date;
+}
+/** A fresh context and state map are created for each HTTP request. */
+export interface FunctionContext {
+    readonly request: Request & {
+        readonly params: Record<string, string>;
+    };
+    readonly params: Record<string, string>;
+    readonly query: URLSearchParams;
+    readonly state: Map<string, unknown>;
+    readonly runtime: WorkerRuntime;
+}
+export type FunctionHandler = (context: FunctionContext) => unknown | Promise<unknown>;
+/** May be called once. Direct imports between functions do not re-enter interception. */
+export type Next = (context?: FunctionContext) => Promise<Response>;
+export type Interceptor = (context: FunctionContext, next: Next) => unknown | Promise<unknown>;
+export interface WorkerLifecycle {
+    default?: Interceptor;
+    onStart?(runtime: WorkerRuntime): unknown | Promise<unknown>;
+    onStop?(runtime: WorkerRuntime): unknown | Promise<unknown>;
+    onError?(error: unknown, context: FunctionContext): unknown | Promise<unknown>;
+}

package/dist/esm/worker.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evumi/berth",
-  "version": "0.0.9",
-  "description": "Client for Berth project Queues and Alarms, and the verifier for signed push deliveries.",
+  "version": "0.0.10",
+  "description": "Berth worker types, document queries on SQLite/libSQL, Queues, Alarms, and signed delivery verification.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,6 +26,46 @@
         "types": "./dist/cjs/index.d.ts",
         "default": "./dist/cjs/index.js"
       }
+    },
+    "./documents": {
+      "import": {
+        "types": "./dist/esm/documents.d.ts",
+        "default": "./dist/esm/documents.js"
+      },
+      "require": {
+        "types": "./dist/cjs/documents.d.ts",
+        "default": "./dist/cjs/documents.js"
+      }
+    },
+    "./documents/bun": {
+      "import": {
+        "types": "./dist/esm/documents/bun.d.ts",
+        "default": "./dist/esm/documents/bun.js"
+      },
+      "require": {
+        "types": "./dist/cjs/documents/bun.d.ts",
+        "default": "./dist/cjs/documents/bun.js"
+      }
+    },
+    "./documents/libsql": {
+      "import": {
+        "types": "./dist/esm/documents/libsql.d.ts",
+        "default": "./dist/esm/documents/libsql.js"
+      },
+      "require": {
+        "types": "./dist/cjs/documents/libsql.d.ts",
+        "default": "./dist/cjs/documents/libsql.js"
+      }
+    },
+    "./worker": {
+      "import": {
+        "types": "./dist/esm/worker.d.ts",
+        "default": "./dist/esm/worker.js"
+      },
+      "require": {
+        "types": "./dist/cjs/worker.d.ts",
+        "default": "./dist/cjs/worker.js"
+      }
     }
   },
   "files": [
@@ -35,14 +75,25 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/cjs-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && vitest run"
+    "test": "pnpm run build && vitest run",
+    "bench:documents": "bun bench/documents.ts",
+    "test:bun": "bun test/documents.bun.ts && bun test/documents.concurrency.bun.ts"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
     "typescript": "6.0.3",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "@libsql/client": "^0.17.0"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "@libsql/client": "^0.17.0"
+  },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    }
   }
 }