@hachej/boring-files 0.0.0-stage → 0.2.0

package/dist/remote.js

@@ -0,0 +1,92 @@
+import { PublicationNotDispatchedError, identifier, publicationDigest, publicationSnapshot } from './publication-input.js';
+import { contentType, encode, envelope, identity, jsonBody, limit, lookupResult, observe, publicationResult, readResult, readSnapshot, sameIdentity, schema, version } from './remote-protocol.js';
+import { randomUUID } from './platform.js';
+export { createResourceHandler } from './remote-handler.js';
+export function createResourceClient(options) {
+    if (options.publication && !options.reconciliation)
+        throw new TypeError('A publishing resource client needs reconciliation: a lost save acknowledgement could otherwise never be resolved');
+    const selected = identity(options.identity), endpoint = new URL(options.endpoint);
+    if (!['https:', 'http:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash)
+        throw new TypeError('Expected an HTTP endpoint without credentials or fragment');
+    const fetch = options.fetch;
+    const requestLimit = limit(options.maxRequestBytes ?? 4_194_304), responseLimit = limit(options.maxResponseBytes ?? 8_388_608);
+    async function invoke(call, signal) {
+        let dispatched = false;
+        const abort = new AbortController();
+        const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+        try {
+            if (combined.aborted)
+                throw new Error('Resource observation aborted');
+            const requestId = randomUUID();
+            const body = encode({ schema, version, requestId, identity: selected, ...call }, requestLimit);
+            const request = new Request(endpoint, { method: 'POST', headers: { 'content-type': contentType }, body, redirect: 'error', signal: combined });
+            if (combined.aborted)
+                throw new Error('Resource observation aborted');
+            dispatched = true;
+            const pending = fetch(request);
+            void pending.then(response => { if (combined.aborted)
+                void response.body?.cancel().catch(() => { }); }, () => { });
+            const response = await observe(pending, combined);
+            if (response.redirected || response.status !== 200) {
+                void response.body?.cancel().catch(() => { });
+                throw new Error('Remote resource response unavailable');
+            }
+            const result = envelope(await jsonBody(response, responseLimit, combined));
+            if (result.requestId !== requestId || result.kind !== call.kind || !sameIdentity(result.identity, selected))
+                throw new TypeError('Resource response association mismatch');
+            return result.value;
+        }
+        catch {
+            if (call.kind === 'publish' && !dispatched)
+                throw new PublicationNotDispatchedError(call.value.operationId);
+            throw new Error('Remote resource operation is unconfirmed');
+        }
+        finally {
+            abort.abort();
+        }
+    }
+    return {
+        read: async (request, signal) => {
+            const captured = readSnapshot(request);
+            try {
+                return readResult(await invoke({ kind: 'read', value: captured }, signal), captured, true);
+            }
+            catch {
+                return { kind: 'unavailable', reason: 'Remote resource read is unconfirmed' };
+            }
+        },
+        ...(options.publication ? {
+            publish: async (request, signal) => {
+                const captured = publicationSnapshot(request);
+                let digest;
+                try {
+                    if (captured.atomicity !== 'all-or-nothing')
+                        throw new TypeError('Remote per-change publication is not qualified');
+                    digest = await publicationDigest(captured);
+                }
+                catch {
+                    throw new PublicationNotDispatchedError(captured.operationId);
+                }
+                try {
+                    return publicationResult(await invoke({ kind: 'publish', value: captured }, signal), captured.operationId, selected, captured, digest);
+                }
+                catch (error) {
+                    if (error instanceof PublicationNotDispatchedError)
+                        throw error;
+                    return { kind: 'unknown', operationId: captured.operationId, reason: 'Remote publication is unconfirmed; reconcile the original operation without automatic replay' };
+                }
+            },
+        } : {}),
+        ...(options.reconciliation ? {
+            lookup: async (operationId, signal) => {
+                const captured = identifier(operationId);
+                try {
+                    return lookupResult(await invoke({ kind: 'lookup', value: captured }, signal), captured, selected);
+                }
+                catch {
+                    return { kind: 'unknown', operationId: captured, reason: 'Remote operation lookup is unconfirmed' };
+                }
+            },
+        } : {}),
+    };
+}

package/dist/request-guard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The one request-body guard of every `create*Handler` in the packages (resource, remote files, remote shell, chat
+ * transport): a JSON content type is required and the body is streamed under a byte cap, so a cross-site `text/plain`
+ * form POST and an oversized body are both refused before any parsing or full buffering. `npm run check` fails when a
+ * `create*Handler` does not import this module, so the handlers cannot drift apart.
+ */
+export declare const JSON_CONTENT_TYPE = "application/json";
+/** A refused request body. `status` is the HTTP status the handler answers with. */
+export declare class RequestGuardError extends Error {
+    readonly status: 400 | 413 | 415;
+    constructor(status: 400 | 413 | 415, message: string);
+}
+/** The HTTP status for a guard refusal, or 400 for any other body failure. */
+export declare function guardStatus(error: unknown): 400 | 413 | 415;
+export declare function hasJsonContentType(headers: Headers): boolean;
+/** Read a stream as JSON without ever holding more than `maximum` bytes. No content-type check: see `readJsonBody`. */
+export declare function readBoundedJson(body: ReadableStream<Uint8Array> | null, maximum: number, signal?: AbortSignal): Promise<unknown>;
+/** Require `application/json`, refuse a declared length over the cap early, then read the body under the cap. */
+export declare function readJsonBody(message: Request | Response, maximum: number, signal?: AbortSignal): Promise<unknown>;
+//# sourceMappingURL=request-guard.d.ts.map

package/dist/request-guard.js

@@ -0,0 +1,75 @@
+/**
+ * The one request-body guard of every `create*Handler` in the packages (resource, remote files, remote shell, chat
+ * transport): a JSON content type is required and the body is streamed under a byte cap, so a cross-site `text/plain`
+ * form POST and an oversized body are both refused before any parsing or full buffering. `npm run check` fails when a
+ * `create*Handler` does not import this module, so the handlers cannot drift apart.
+ */
+export const JSON_CONTENT_TYPE = 'application/json';
+/** A refused request body. `status` is the HTTP status the handler answers with. */
+export class RequestGuardError extends Error {
+    status;
+    constructor(status, message) { super(message); this.name = 'RequestGuardError'; this.status = status; }
+}
+/** The HTTP status for a guard refusal, or 400 for any other body failure. */
+export function guardStatus(error) {
+    return error instanceof RequestGuardError ? error.status : 400;
+}
+export function hasJsonContentType(headers) {
+    return headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() === JSON_CONTENT_TYPE;
+}
+/** Read a stream as JSON without ever holding more than `maximum` bytes. No content-type check: see `readJsonBody`. */
+export async function readBoundedJson(body, maximum, signal) {
+    if (!Number.isSafeInteger(maximum) || maximum < 1)
+        throw new TypeError('Expected a positive byte limit');
+    if (!body)
+        throw new RequestGuardError(400, 'Missing request body');
+    const reader = body.getReader();
+    let fail;
+    const abort = new Promise((_, reject) => {
+        fail = () => reject(new Error('Request body read aborted'));
+        if (signal?.aborted)
+            fail();
+        else
+            signal?.addEventListener('abort', fail, { once: true });
+    });
+    abort.catch(() => { });
+    try {
+        let size = 0, buffer = new Uint8Array(Math.min(maximum, 16_384));
+        while (true) {
+            const item = await (signal ? Promise.race([reader.read(), abort]) : reader.read());
+            if (item.done)
+                break;
+            if (item.value.byteLength > maximum - size)
+                throw new RequestGuardError(413, 'Request body exceeds its byte limit');
+            const next = size + item.value.byteLength;
+            if (next > buffer.byteLength) {
+                const grown = new Uint8Array(Math.min(maximum, Math.max(next, buffer.byteLength * 2)));
+                grown.set(buffer.subarray(0, size));
+                buffer = grown;
+            }
+            buffer.set(item.value, size);
+            size = next;
+        }
+        try {
+            return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)));
+        }
+        catch {
+            throw new RequestGuardError(400, 'Request body is not valid JSON');
+        }
+    }
+    finally {
+        if (fail)
+            signal?.removeEventListener('abort', fail);
+        void reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** Require `application/json`, refuse a declared length over the cap early, then read the body under the cap. */
+export async function readJsonBody(message, maximum, signal) {
+    if (!hasJsonContentType(message.headers))
+        throw new RequestGuardError(415, 'Request content type must be application/json');
+    const declared = Number(message.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maximum)
+        throw new RequestGuardError(413, 'Request body exceeds its byte limit');
+    return readBoundedJson(message.body, maximum, signal);
+}

package/dist/revision-contracts.d.ts

@@ -0,0 +1,48 @@
+import type { ResourceClient } from './client.js';
+import type { ResourceAccess, ResourceLocator } from './contracts.js';
+import type { ResourceIdentity } from './remote-protocol.js';
+import type { WorkspaceKey } from './workspace-identity.js';
+export interface FileEntry {
+    readonly path: string;
+    readonly kind: 'file' | 'directory';
+    readonly size: number;
+}
+export interface FilePage {
+    readonly entries: readonly FileEntry[];
+    readonly cursor?: string;
+}
+export interface FileListRequest {
+    readonly directory?: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface FileSearchRequest {
+    readonly query: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface SavedRevision {
+    readonly revision: string;
+    readonly savedAt: number;
+}
+export interface WorkspaceCatalog {
+    readonly list: (request: FileListRequest, access: ResourceAccess) => Promise<FilePage>;
+    readonly search: (request: FileSearchRequest, access: ResourceAccess) => Promise<FilePage>;
+    readonly history: (path: string, access: ResourceAccess) => Promise<readonly SavedRevision[]>;
+}
+export declare class RevisionError extends Error {
+    readonly kind: 'denied' | 'unavailable' | 'invalid' | 'aborted';
+    constructor(kind: 'denied' | 'unavailable' | 'invalid' | 'aborted', message: string);
+}
+/** One authenticated binding for viewers, file browsing and publication. */
+export interface RevisionProvider extends ResourceClient {
+    readonly identity: ResourceIdentity;
+    readonly workspace: WorkspaceKey;
+    readonly locate: (path: string) => ResourceLocator;
+    readonly publish: NonNullable<ResourceClient['publish']>;
+    readonly lookup: NonNullable<ResourceClient['lookup']>;
+    readonly list: (request: FileListRequest, signal?: AbortSignal) => Promise<FilePage>;
+    readonly search: (request: FileSearchRequest, signal?: AbortSignal) => Promise<FilePage>;
+    readonly history: (path: string, signal?: AbortSignal) => Promise<readonly SavedRevision[]>;
+}
+//# sourceMappingURL=revision-contracts.d.ts.map

package/dist/revision-contracts.js

@@ -0,0 +1,8 @@
+export class RevisionError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'RevisionError';
+    }
+}

package/dist/revision-handler.d.ts

@@ -0,0 +1,11 @@
+import type { ResourceAccess } from './contracts.js';
+import type { WorkspaceResourceProvider } from './workspace.js';
+export interface RevisionHandlerOptions {
+    readonly resolve: (request: Request) => Promise<null | {
+        readonly provider: WorkspaceResourceProvider;
+        readonly access: ResourceAccess;
+        readonly release?: () => void | Promise<void>;
+    }>;
+}
+export declare function createRevisionHandler(options: RevisionHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=revision-handler.d.ts.map

package/dist/revision-handler.js

@@ -0,0 +1,105 @@
+import { createResourceHandler } from './remote-handler.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record, savedRevisions } from './revision-protocol.js';
+import { guardStatus, readJsonBody, RequestGuardError } from './request-guard.js';
+import { accessSnapshot, identifier } from './publication-input.js';
+import { RevisionError } from './revision-contracts.js';
+function listRequest(value) {
+    const data = record(value);
+    if ((data.directory !== undefined && typeof data.directory !== 'string') || (data.cursor !== undefined && typeof data.cursor !== 'string') || (data.limit !== undefined && typeof data.limit !== 'number'))
+        throw new RevisionError('invalid', 'Invalid listing request');
+    return { ...(typeof data.directory === 'string' ? { directory: data.directory } : {}), ...(typeof data.cursor === 'string' ? { cursor: data.cursor } : {}), ...(typeof data.limit === 'number' ? { limit: data.limit } : {}) };
+}
+export function createRevisionHandler(options) {
+    return async (request) => {
+        let release;
+        const operations = new Set();
+        const hold = (pending) => {
+            operations.add(pending);
+            void pending.then(() => operations.delete(pending), () => operations.delete(pending));
+            return pending;
+        };
+        const refuse = (status) => new Response(null, { status, headers: { 'cache-control': 'no-store' } });
+        try {
+            if (request.method !== 'GET' && request.method !== 'POST')
+                return refuse(405);
+            if (request.signal.aborted)
+                return refuse(403);
+            const selected = await options.resolve(request);
+            if (!selected)
+                return refuse(403);
+            release = selected.release;
+            const captured = accessSnapshot(selected.access);
+            const access = { ...captured, signal: captured.signal ? AbortSignal.any([captured.signal, request.signal]) : request.signal };
+            if (access.signal.aborted)
+                return refuse(403);
+            const association = binding({ identity: captured, workspace: selected.provider.identity });
+            const respond = (value) => Response.json(value, { headers: { 'cache-control': 'no-store' } });
+            if (request.method === 'GET')
+                return respond(association);
+            const header = request.headers.get(bindingHeader);
+            if (!header || header.length > 16384)
+                return refuse(403);
+            let requested;
+            try {
+                requested = bindingValue(binding(JSON.parse(decodeURIComponent(header))));
+            }
+            catch {
+                return refuse(403);
+            }
+            if (requested !== bindingValue(association))
+                return refuse(409);
+            const provider = selected.provider;
+            if (!request.headers.has(catalogHeader))
+                return await createResourceHandler({
+                    authenticate: async () => access,
+                    reader: { read: (value, context) => hold(provider.read(value, context)) },
+                    publisher: { publish: (value, context) => hold(provider.publication.publish(value, context)) },
+                    lookup: { lookup: (value, context) => hold(provider.reconciliation.lookup(value, context)) },
+                })(request);
+            const input = record(await readJsonBody(request, 32_768, access.signal));
+            const requestId = identifier(input.requestId);
+            let value;
+            switch (input.kind) {
+                case 'list':
+                    value = filePage(await provider.catalog.list(listRequest(input.value), access));
+                    break;
+                case 'search': {
+                    const data = record(input.value);
+                    if (typeof data.query !== 'string')
+                        throw new RevisionError('invalid', 'Invalid filename query');
+                    const query = { ...listRequest(data), query: data.query };
+                    value = filePage(await provider.catalog.search(query, access));
+                    break;
+                }
+                case 'history':
+                    if (typeof input.value !== 'string')
+                        throw new RevisionError('invalid', 'Invalid history path');
+                    value = savedRevisions(await provider.catalog.history(input.value, access));
+                    break;
+                default: return refuse(400);
+            }
+            if (access.signal.aborted)
+                return refuse(403);
+            const body = JSON.stringify({ ...association, requestId, kind: input.kind, value });
+            if (new TextEncoder().encode(body).byteLength > 8_388_608)
+                return refuse(503);
+            return new Response(body, { headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+        }
+        catch (error) {
+            return refuse(error instanceof RevisionError ? error.kind === 'invalid' ? 400 : error.kind === 'denied' || error.kind === 'aborted' ? 403 : 503 : error instanceof RequestGuardError || error instanceof TypeError ? guardStatus(error) : 503);
+        }
+        finally {
+            await Promise.allSettled([...operations]);
+            try {
+                await release?.();
+            }
+            catch {
+                return refuse(503);
+            }
+            finally {
+                if (!request.bodyUsed)
+                    void request.body?.cancel().catch(() => { });
+            }
+        }
+    };
+}

package/dist/revision-protocol.d.ts

@@ -0,0 +1,15 @@
+import type { ResourceIdentity } from './remote-protocol.js';
+import type { WorkspaceKey } from './workspace.js';
+import type { FilePage, SavedRevision } from './revision-contracts.js';
+export declare const bindingHeader = "x-boring-workspace";
+export declare const catalogHeader = "x-boring-catalog";
+export interface RevisionBinding {
+    readonly identity: ResourceIdentity;
+    readonly workspace: WorkspaceKey;
+}
+export declare function record(value: unknown): Record<string, unknown>;
+export declare function binding(value: unknown): RevisionBinding;
+export declare const bindingValue: (value: RevisionBinding) => string;
+export declare function filePage(value: unknown): FilePage;
+export declare function savedRevisions(value: unknown): readonly SavedRevision[];
+//# sourceMappingURL=revision-protocol.d.ts.map

package/dist/revision-protocol.js

@@ -0,0 +1,42 @@
+import { identifier, locator } from './publication-input.js';
+import { RevisionError } from './revision-contracts.js';
+const catalogPath = (path) => locator({ resource: { providerId: 'catalog', path }, view: { kind: 'published' } }).resource.path;
+export const bindingHeader = 'x-boring-workspace';
+export const catalogHeader = 'x-boring-catalog';
+export function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new RevisionError('invalid', 'Invalid revision response');
+    return value;
+}
+export function binding(value) {
+    const data = record(value), workspace = record(data.workspace), person = record(data.identity);
+    return { identity: { principalId: identifier(person.principalId), scopeId: identifier(person.scopeId), initiatorId: identifier(person.initiatorId) }, workspace: {
+            providerId: identifier(workspace.providerId), instanceId: identifier(workspace.instanceId),
+            incarnation: identifier(workspace.incarnation), viewId: identifier(workspace.viewId),
+        } };
+}
+export const bindingValue = (value) => encodeURIComponent(JSON.stringify(binding(value)));
+export function filePage(value) {
+    const data = record(value);
+    if (!Array.isArray(data.entries) || data.entries.length > 500 || (data.cursor !== undefined && (typeof data.cursor !== 'string' || data.cursor.length > 16384)))
+        throw new RevisionError('invalid', 'Invalid file page');
+    const entries = data.entries.map((item) => {
+        const entry = record(item);
+        if ((entry.kind !== 'file' && entry.kind !== 'directory') || typeof entry.size !== 'number' || !Number.isSafeInteger(entry.size) || entry.size < 0 || typeof entry.path !== 'string')
+            throw new RevisionError('invalid', 'Invalid file entry');
+        return { path: catalogPath(entry.path), kind: entry.kind, size: entry.size };
+    });
+    if (new Set(entries.map(entry => entry.path)).size !== entries.length)
+        throw new RevisionError('invalid', 'Duplicate file entries');
+    return { entries, ...(typeof data.cursor === 'string' ? { cursor: data.cursor } : {}) };
+}
+export function savedRevisions(value) {
+    if (!Array.isArray(value) || value.length > 100_000)
+        throw new RevisionError('invalid', 'Invalid file history');
+    return value.map(item => {
+        const entry = record(item);
+        if (typeof entry.savedAt !== 'number' || !Number.isSafeInteger(entry.savedAt) || entry.savedAt < 0)
+            throw new RevisionError('invalid', 'Invalid save timestamp');
+        return { revision: identifier(entry.revision), savedAt: entry.savedAt };
+    });
+}

package/dist/revision.d.ts

@@ -0,0 +1,8 @@
+import type { RevisionProvider } from './revision-contracts.js';
+export * from './revision-contracts.js';
+export declare function connectRevisionProvider(options: {
+    readonly endpoint: string | URL;
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly signal?: AbortSignal;
+}): Promise<RevisionProvider>;
+//# sourceMappingURL=revision.d.ts.map

package/dist/revision.js

@@ -0,0 +1,57 @@
+import { createResourceClient } from './remote.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record, savedRevisions } from './revision-protocol.js';
+import { readJsonBody } from './request-guard.js';
+import { RevisionError } from './revision-contracts.js';
+import { observe } from './remote-protocol.js';
+import { randomUUID } from './platform.js';
+import { locator } from './publication-input.js';
+export * from './revision-contracts.js';
+export async function connectRevisionProvider(options) {
+    const endpoint = new URL(options.endpoint), fetch = options.fetch;
+    if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash)
+        throw new TypeError('Expected an HTTP endpoint without credentials or fragment');
+    async function send(request) {
+        try {
+            const pending = fetch(request);
+            void pending.then(response => { if (request.signal.aborted)
+                void response.body?.cancel().catch(() => { }); }, () => { });
+            const response = await observe(pending, request.signal);
+            if (request.signal.aborted) {
+                void response.body?.cancel().catch(() => { });
+                throw new RevisionError('aborted', 'File request was cancelled');
+            }
+            if (response.redirected || !response.ok) {
+                void response.body?.cancel().catch(() => { });
+                throw new RevisionError(response.status === 403 || response.status === 409 ? 'denied' : response.status === 400 ? 'invalid' : 'unavailable', 'The selected workspace is unavailable or no longer authorized');
+            }
+            return await readJsonBody(response, 8_388_608, request.signal);
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                throw new RevisionError('aborted', 'File request was cancelled');
+            if (error instanceof RevisionError)
+                throw error;
+            throw new RevisionError('unavailable', 'The file request could not be completed');
+        }
+    }
+    const selected = binding(await send(new Request(endpoint, { method: 'GET', redirect: 'error', ...(options.signal ? { signal: options.signal } : {}) })));
+    const bound = bindingValue(selected);
+    const client = createResourceClient({ endpoint, identity: selected.identity, publication: true, reconciliation: true,
+        fetch: request => { const headers = new Headers(request.headers); headers.set(bindingHeader, bound); return fetch(new Request(request, { headers })); } });
+    async function invoke(kind, value, signal) {
+        const requestId = randomUUID();
+        const result = record(await send(new Request(endpoint, { method: 'POST', redirect: 'error', headers: { 'content-type': 'application/json', [bindingHeader]: bound, [catalogHeader]: '1' }, body: JSON.stringify({ requestId, kind, value }), ...(signal ? { signal } : {}) })));
+        if (bindingValue(binding(result)) !== bound || result.kind !== kind || result.requestId !== requestId)
+            throw new RevisionError('denied', 'The response belongs to another workspace');
+        return result.value;
+    }
+    if (!client.publish || !client.lookup)
+        throw new Error('Publishing client lacks reconciliation');
+    return {
+        ...client, publish: client.publish, lookup: client.lookup, identity: Object.freeze(selected.identity), workspace: Object.freeze(selected.workspace),
+        locate: path => locator({ resource: { providerId: selected.workspace.providerId, path }, view: { kind: 'published' } }),
+        list: async (request, signal) => filePage(await invoke('list', request, signal)),
+        search: async (request, signal) => filePage(await invoke('search', request, signal)),
+        history: async (path, signal) => savedRevisions(await invoke('history', path, signal)),
+    };
+}

package/dist/sqlite-batch.d.ts

@@ -0,0 +1,19 @@
+import type { SqliteConnection } from './sqlite.js';
+/**
+ * Internal (not a package export): what the workspace provider needs from the SQLite file system to commit a multi-file batch in
+ * one transaction. Registered by `openSqliteFileSystem` against the file system object it returns, so the provider keeps taking a
+ * plain Pi `FileSystem`. Both functions are synchronous and run inside `connection.transaction`.
+ */
+export interface SqliteBatch {
+    readonly connection: SqliteConnection;
+    /** The bytes of the regular file at an absolute path, `null` when nothing is there, `undefined` when it is not a file. */
+    readonly bytes: (path: string) => Uint8Array | null | undefined;
+    /** Write a regular file at an absolute path, creating its missing parent directories. Throws a Pi `FileError` on failure. */
+    readonly write: (path: string, bytes: Uint8Array) => void;
+}
+export declare const registerSqliteBatch: (fs: object, batch: SqliteBatch) => void;
+export declare const sqliteBatchOf: (fs: object) => SqliteBatch | undefined;
+/** The journal's connection, so the provider can commit the bytes and the receipt in one transaction when they share a database. */
+export declare const registerJournalConnection: (journal: object, connection: SqliteConnection) => void;
+export declare const journalConnectionOf: (journal: object) => SqliteConnection | undefined;
+//# sourceMappingURL=sqlite-batch.d.ts.map

package/dist/sqlite-batch.js

@@ -0,0 +1,7 @@
+const batches = new WeakMap();
+const journals = new WeakMap();
+export const registerSqliteBatch = (fs, batch) => { batches.set(fs, batch); };
+export const sqliteBatchOf = (fs) => batches.get(fs);
+/** The journal's connection, so the provider can commit the bytes and the receipt in one transaction when they share a database. */
+export const registerJournalConnection = (journal, connection) => { journals.set(journal, connection); };
+export const journalConnectionOf = (journal) => journals.get(journal);

package/dist/sqlite-durable-object.d.ts

@@ -0,0 +1,24 @@
+import type { SqliteConnection } from './sqlite.js';
+type DurableValue = ArrayBuffer | string | number | null;
+/**
+ * The part of a Cloudflare Durable Object's `ctx.storage` this adapter uses, declared structurally so the package needs no
+ * Cloudflare types: `sql.exec(query, ...bindings)` returns a cursor and `transactionSync(work)` runs `work` as one SQLite transaction.
+ */
+export interface DurableObjectSqlStorage {
+    readonly sql: {
+        readonly exec: (query: string, ...bindings: DurableValue[]) => {
+            readonly toArray: () => Record<string, unknown>[];
+        };
+    };
+    readonly transactionSync: <Value>(work: () => Value) => Value;
+}
+/**
+ * A `SqliteConnection` over a SQLite-backed Durable Object's storage, for `openSqliteFileSystem({ connection })` and `createWorkspaceJournal(connection)`. Statements run on
+ * the object's own synchronous SQL API. A `write` transaction is `transactionSync`: SQLite commits every statement of the callback
+ * together, or rolls all of them back when it throws, and nothing else in the object runs in between because the callback is
+ * synchronous. A `read` runs the callback directly, which is consistent for the same reason. The object owns the database:
+ * the connection has no `close`.
+ */
+export declare function durableObjectSqliteConnection(storage: DurableObjectSqlStorage): SqliteConnection;
+export {};
+//# sourceMappingURL=sqlite-durable-object.d.ts.map

package/dist/sqlite-durable-object.js

@@ -0,0 +1,49 @@
+function binding(value) {
+    if (typeof value === 'bigint') {
+        if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER))
+            throw new RangeError('SQLite integer is outside the safe range');
+        return Number(value);
+    }
+    return value instanceof Uint8Array ? value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) : value;
+}
+/** Blobs come back as ArrayBuffers; the provider reads Uint8Arrays. */
+function row(raw) {
+    for (const key of Object.keys(raw)) {
+        const value = raw[key];
+        if (value instanceof ArrayBuffer)
+            raw[key] = new Uint8Array(value);
+    }
+    return raw;
+}
+/**
+ * A `SqliteConnection` over a SQLite-backed Durable Object's storage, for `openSqliteFileSystem({ connection })` and `createWorkspaceJournal(connection)`. Statements run on
+ * the object's own synchronous SQL API. A `write` transaction is `transactionSync`: SQLite commits every statement of the callback
+ * together, or rolls all of them back when it throws, and nothing else in the object runs in between because the callback is
+ * synchronous. A `read` runs the callback directly, which is consistent for the same reason. The object owns the database:
+ * the connection has no `close`.
+ */
+export function durableObjectSqliteConnection(storage) {
+    const exec = (sql, params) => storage.sql.exec(sql, ...params.map(binding));
+    let depth = 0;
+    return {
+        exec: sql => { exec(sql, []).toArray(); },
+        run: (sql, ...params) => { exec(sql, params).toArray(); },
+        get: (sql, ...params) => {
+            const [first] = exec(sql, params).toArray();
+            return first === undefined ? undefined : row(first);
+        },
+        all: (sql, ...params) => exec(sql, params).toArray().map(item => row(item)),
+        // A transaction opened inside another one joins it.
+        transaction: (mode, work) => {
+            if (mode === 'read' || depth > 0)
+                return work();
+            depth++;
+            try {
+                return storage.transactionSync(work);
+            }
+            finally {
+                depth--;
+            }
+        },
+    };
+}

package/dist/sqlite-filesystem.d.ts

@@ -0,0 +1,16 @@
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+import type { SqliteConnection } from './sqlite.js';
+export interface SqliteFileSystemOptions {
+    /** The database. The host owns it: `cleanup` leaves it open. */
+    readonly connection: SqliteConnection;
+    /** Which workspace's rows: one database can hold several workspaces. */
+    readonly workspace: string;
+    /** The absolute working directory, created when missing (for example `/workspace`). Relative paths resolve against `cwd`. */
+    readonly cwd: string;
+}
+/** A Pi `FileSystem` plus the incarnation of its rows: new when the workspace was first created in this database. */
+export interface SqliteFileSystem extends FileSystem {
+    readonly incarnation: string;
+}
+export declare function openSqliteFileSystem(options: SqliteFileSystemOptions): SqliteFileSystem;
+//# sourceMappingURL=sqlite-filesystem.d.ts.map