@fungi.computer/watchdog 0.0.0-stage → 0.0.1

package/dist/node-sqlite.js

@@ -0,0 +1,63 @@
+import * as Schema from "effect/Schema";
+import { watchdogSqliteRowSchema } from "./effect.js";
+const decodeRow = Schema.decodeUnknownSync(watchdogSqliteRowSchema);
+function fromSqlite(value) {
+    if (Schema.is(Schema.BigInt)(value))
+        return Number(value);
+    if (ArrayBuffer.isView(value))
+        return new Uint8Array(value).slice().buffer;
+    return value;
+}
+/** Adapt a caller-owned Node SQLite database; the caller retains its lifetime. */
+export function fromNodeSqlite(database) {
+    let transaction = 0;
+    return {
+        sql: {
+            exec: (statement, ...bindings) => {
+                const prepared = database.prepare(statement);
+                const values = bindings.map((value) => value instanceof ArrayBuffer ? new Uint8Array(value) : value);
+                let rows;
+                if (prepared.columns().length > 0) {
+                    rows = prepared
+                        .all(...values)
+                        .map((row) => decodeRow(Object.fromEntries(Object.entries(row).map(([key, value]) => [
+                        key,
+                        fromSqlite(value),
+                    ]))));
+                }
+                else {
+                    // Schema owners supply several unbound DDL statements in one call.
+                    // DatabaseSync.exec owns that grammar; prepare/run executes only one.
+                    if (values.length === 0)
+                        database.exec(statement);
+                    else
+                        prepared.run(...values);
+                    rows = [];
+                }
+                return {
+                    toArray: () => rows,
+                    one: () => {
+                        const row = rows[0];
+                        if (rows.length !== 1 || row === undefined)
+                            throw new Error(`Expected exactly one SQLite row; got ${String(rows.length)}`);
+                        return row;
+                    },
+                };
+            },
+        },
+        transactionSync: (operation) => {
+            const name = `watchdog_owner_${String(transaction++)}`;
+            database.exec(`SAVEPOINT ${name}`);
+            try {
+                const result = operation();
+                database.exec(`RELEASE ${name}`);
+                return result;
+            }
+            catch (cause) {
+                database.exec(`ROLLBACK TO ${name}`);
+                database.exec(`RELEASE ${name}`);
+                throw cause;
+            }
+        },
+    };
+}

package/dist/postgres.d.ts

@@ -0,0 +1,22 @@
+import type { Pool, PoolClient } from "pg";
+import type { WatchdogQueuedJob } from "./effect.js";
+import { type AsyncWatchdogOptions, type AsyncWatchdogRuntime } from "./internal/async-runtime.js";
+export type { AsyncWatchdogOptions, AsyncWatchdogRuntime, } from "./internal/async-runtime.js";
+/** PostgreSQL runtime with admission joined to the caller's checked-out client. */
+export type PostgresWatchdog = AsyncWatchdogRuntime & Readonly<{
+    /** Enqueue on the existing transaction; never BEGIN, COMMIT or ROLLBACK here. */
+    enqueue: (client: Pick<PoolClient, "query">, job: WatchdogQueuedJob) => Promise<void>;
+}>;
+/** Package-owned schema statements, to run through the deployment migration owner. */
+export declare const watchdogPostgresSchema: readonly string[];
+/** Open the shared Effect engine on a migrated PostgreSQL database. */
+export declare function createPostgresWatchdog(options: AsyncWatchdogOptions & Readonly<{
+    database: Pick<Pool, "query">;
+}>): PostgresWatchdog;
+/** Parameterized queue purge joined to a producer's existing PostgreSQL transaction. */
+export type PostgresPurgeStatement = Readonly<{
+    text: string;
+    values: readonly (string | number | null)[];
+}>;
+/** Purge every attempt in the queues yielded by trusted producer SQL. */
+export declare function purgePostgresQueues(source: PostgresPurgeStatement): readonly PostgresPurgeStatement[];

package/dist/postgres.js

@@ -0,0 +1,31 @@
+import { createAsyncRuntime, } from "./internal/async-runtime.js";
+import { enqueueStatement, schemaStatements, } from "./internal/async-sql.js";
+/** Package-owned schema statements, to run through the deployment migration owner. */
+export const watchdogPostgresSchema = schemaStatements(true);
+/** Open the shared Effect engine on a migrated PostgreSQL database. */
+export function createPostgresWatchdog(options) {
+    const runtime = createAsyncRuntime({
+        clock: options.now === undefined
+            ? "EXTRACT(EPOCH FROM clock_timestamp())*1000"
+            : undefined,
+        query: async (statement) => (await options.database.query(statement.text, [
+            ...statement.values,
+        ])).rows,
+    }, options);
+    return {
+        ...runtime,
+        enqueue: async (client, job) => {
+            const statement = enqueueStatement(job);
+            await client.query(statement.text, [...statement.values]);
+        },
+    };
+}
+/** Purge every attempt in the queues yielded by trusted producer SQL. */
+export function purgePostgresQueues(source) {
+    return [
+        {
+            text: `DELETE FROM watchdog_jobs WHERE queue_name IN (SELECT queue_name FROM (${source.text}) AS erasure)`,
+            values: source.values,
+        },
+    ];
+}

package/docs/api/README.md

@@ -0,0 +1,17 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/watchdog**
+
+---
+
+# @fungi.computer/watchdog
+
+## Modules
+
+| Module                        | Description |
+| ----------------------------- | ----------- |
+| [d1](d1.md)                   | -           |
+| [effect](effect.md)           | -           |
+| [index](index.md)             | -           |
+| [node-sqlite](node-sqlite.md) | -           |
+| [postgres](postgres.md)       | -           |

package/docs/api/d1.md

@@ -0,0 +1,162 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/watchdog**](README.md)
+
+---
+
+[@fungi.computer/watchdog](README.md) / d1
+
+# d1
+
+## Type Aliases
+
+### D1AdmissionSource
+
+```ts
+type D1AdmissionSource = Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>;
+```
+
+Trusted parameter-bound SELECT yielding queued job fields; never lifecycle
+fields.
+
+---
+
+### D1Admission
+
+```ts
+type D1Admission = Readonly<{
+  enqueue: (job) => D1PreparedStatement;
+  enqueueFromSelect: (source) => D1PreparedStatement;
+}>;
+```
+
+D1 runtime with admission statements that join the producer's native batch.
+
+---
+
+### D1Watchdog
+
+```ts
+type D1Watchdog = AsyncWatchdogRuntime & D1Admission;
+```
+
+D1 lifecycle and native transaction admission.
+
+---
+
+### D1PurgeStatement
+
+```ts
+type D1PurgeStatement = Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>;
+```
+
+Parameterized native purge; caller commits it with its own erasure facts.
+
+---
+
+### AsyncWatchdogOptions
+
+```ts
+type AsyncWatchdogOptions = Readonly<{
+  execute: WatchdogExecutor;
+  wake: Readonly<{
+    recompute: () => Promise<void>;
+  }>;
+  now?: () => number;
+}>;
+```
+
+Host execution and wake scheduling for a shared-database Watchdog.
+
+---
+
+### AsyncWatchdogRuntime
+
+```ts
+type AsyncWatchdogRuntime = Omit<WatchdogRuntime, "transactional">;
+```
+
+Shared-database runtime; native admission replaces the SQLite projection.
+
+## Variables
+
+### watchdogD1Schema
+
+```ts
+const watchdogD1Schema: readonly string[];
+```
+
+Package-owned schema statements, to run through the deployment migration owner.
+
+## Functions
+
+### createD1Watchdog()
+
+```ts
+function createD1Watchdog(options): D1Watchdog;
+```
+
+Open the shared Effect engine on a migrated D1 database; no implicit schema
+writes.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                         |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `execute`: [`WatchdogExecutor`](index.md#watchdogexecutor); `wake`: `Readonly`\<\{ `recompute`: () => `Promise`\<`void`\>; \}\>; `now?`: () => `number`; \}\> & `Readonly`\<\{ `database`: `D1Database`; \}\> |
+
+#### Returns
+
+[`D1Watchdog`](#d1watchdog)
+
+---
+
+### prepareD1Admission()
+
+```ts
+function prepareD1Admission(database): D1Admission;
+```
+
+Prepare native admission without constructing an executor or performing I/O.
+
+#### Parameters
+
+| Parameter  | Type         |
+| ---------- | ------------ |
+| `database` | `D1Database` |
+
+#### Returns
+
+[`D1Admission`](#d1admission)
+
+---
+
+### purgeD1Queues()
+
+```ts
+function purgeD1Queues(source): readonly Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>[];
+```
+
+Purge every attempt in selected queues, fencing any executor still holding a
+claim. The trusted SELECT yields queue_name. It never supplies lifecycle
+mutations.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `source`  | [`D1PurgeStatement`](#d1purgestatement) |
+
+#### Returns
+
+readonly `Readonly`\<\{ `text`: `string`; `values`: readonly (`string` \|
+`number` \| `null`)[]; \}\>[]