@abloatai/ablo 0.35.0 → 0.37.0

package/dist/source/adapters/prisma.js

@@ -1,202 +0,0 @@
-/**
- * The Prisma adapter for the data-source interface. It implements
- * {@link DataSourceAdapter} against a Prisma client and passes the same conformance
- * suite as the in-memory reference and the other adapters.
- *
- * The adapter owns the transactional outbox and idempotency bookkeeping, so you
- * never write them: `commit` runs the row mutations, the `ablo_outbox` append, and
- * the `ablo_idempotency` record inside a single `prisma.$transaction`, and
- * `migrations` returns the SQL that creates those two tables.
- *
- * It takes no dependency on `@prisma/client`. The client is accepted structurally
- * as {@link PrismaLike}, so this module compiles without Prisma installed and can
- * be tested with a fake, while a real `PrismaClient` satisfies the shape at the
- * call site.
- */
-import { AbloValidationError } from '../../transaction/errors.js';
-import { outboxEventSchema } from '../contract.js';
-import { adapterTableMigrations } from '../migrations.js';
-import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, SOURCE_IDEMPOTENCY_RETENTION, sourceChangeIntentHash, } from '../idempotency.js';
-import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX, } from '../types.js';
-const lowerFirst = (s) => (s ? s.charAt(0).toLowerCase() + s.slice(1) : s);
-/**
- * Resolves a model's Prisma delegate by name. This is the one unavoidable cast in
- * the adapter, and it reflects a real limit of the type system rather than a
- * shortcut. Writes inside `prisma.$transaction(tx => …)` must go through the
- * transactional client `tx`, and the model is known only as a runtime string.
- * Prisma keys its client by fixed property names (`{ task: TaskDelegate; … }`), so
- * a dynamic `tx[name]` lookup is `unknown` to the compiler: there is no static key
- * to infer from a string. The cast is checked at runtime immediately afterward by
- * confirming that `findMany` is a function on the resolved delegate.
- */
-function delegateFor(client, name) {
-    const delegate = client[name];
-    if (!delegate || typeof delegate.findMany !== 'function') {
-        throw new AbloValidationError(`prismaDataSource: no Prisma delegate "${name}" on the client`, { code: 'source_adapter_misconfigured' });
-    }
-    return delegate;
-}
-/** Translates a source-query `where` tuple set into a Prisma `where` object. */
-function toPrismaWhere(where) {
-    const out = {};
-    for (const clause of where ?? []) {
-        const [field] = clause;
-        if (clause.length === 2) {
-            out[field] = clause[1];
-            continue;
-        }
-        const [, op, value] = clause;
-        switch (op) {
-            case '=':
-                out[field] = value;
-                break;
-            case '!=':
-                out[field] = { not: value };
-                break;
-            case '<':
-                out[field] = { lt: value };
-                break;
-            case '<=':
-                out[field] = { lte: value };
-                break;
-            case '>':
-                out[field] = { gt: value };
-                break;
-            case '>=':
-                out[field] = { gte: value };
-                break;
-            case 'IN':
-                out[field] = { in: value };
-                break;
-            case 'NOT IN':
-                out[field] = { notIn: value };
-                break;
-            case 'LIKE':
-            case 'ILIKE':
-                out[field] = { contains: value, mode: op === 'ILIKE' ? 'insensitive' : 'default' };
-                break;
-            case 'NOT LIKE':
-            case 'NOT ILIKE':
-                out[field] = { not: { contains: value } };
-                break;
-            case 'IS':
-            case 'IS NOT':
-                out[field] = op === 'IS' ? value : { not: value };
-                break;
-        }
-    }
-    return out;
-}
-function findManyArgs(query) {
-    return {
-        where: toPrismaWhere(query?.where),
-        ...(typeof query?.limit === 'number' ? { take: query.limit } : {}),
-        ...(query?.orderBy ? { orderBy: { [query.orderBy]: query.order ?? 'asc' } } : {}),
-    };
-}
-function rowId(op) {
-    const id = op.id ?? op.input?.id;
-    if (typeof id !== 'string' || id.length === 0) {
-        throw new AbloValidationError(`operation on "${op.model}" requires an id`, { code: 'source_operation_id_required' });
-    }
-    return id;
-}
-export function prismaDataSource(prisma, schema, options = {}) {
-    const delegateName = options.delegateName ?? lowerFirst;
-    void schema; // held for typed reads and model validation
-    const applyOperation = async (tx, op) => {
-        const delegate = delegateFor(tx, delegateName(op.model));
-        const id = rowId(op);
-        switch (op.type) {
-            case 'CREATE':
-                return delegate.create({ data: { id, ...(op.input ?? {}) } });
-            case 'UPDATE':
-                return delegate.update({ where: { id }, data: { ...(op.input ?? {}) } });
-            case 'ARCHIVE':
-                return delegate.update({ where: { id }, data: { ...(op.input ?? {}), archivedAt: new Date() } });
-            case 'UNARCHIVE':
-                return delegate.update({ where: { id }, data: { ...(op.input ?? {}), archivedAt: null } });
-            case 'DELETE':
-                return delegate.delete({ where: { id } });
-        }
-    };
-    return {
-        capabilities: {
-            transactions: true,
-            propose: false,
-            schemaIntrospection: true,
-            postgresWalEcho: true,
-            outboxEvents: true,
-        },
-        migrations() {
-            return adapterTableMigrations();
-        },
-        async read(req) {
-            const delegate = delegateFor(prisma, delegateName(req.model));
-            if (req.kind === 'load') {
-                const row = await delegate.findUnique({ where: { id: req.id } });
-                return row ? [row] : [];
-            }
-            return delegate.findMany(findManyArgs(req.query));
-        },
-        async commit(change) {
-            const requestHash = sourceChangeIntentHash(change);
-            return prisma.$transaction(async (tx) => {
-                // Idempotency: a duplicate scoped correlation returns the original rows.
-                const cached = await tx.$queryRawUnsafe(`SELECT response, request_hash AS "requestHash", expires_at AS "expiresAt"
-             FROM ablo_idempotency WHERE client_tx_id = $1 LIMIT 1`, change.correlationId);
-                const cachedRow = cached[0];
-                if (cachedRow) {
-                    assertSourceIdempotencyIntent(cachedRow.requestHash, requestHash);
-                    assertSourceIdempotencyRetention(cachedRow.expiresAt);
-                    return { rows: cachedRow.response };
-                }
-                const rows = [];
-                for (const [index, op] of change.operations.entries()) {
-                    const row = await applyOperation(tx, op);
-                    rows.push(row);
-                    const entityId = String(row.id ?? rowId(op));
-                    // Transactional outbox: one event per operation, written in this same transaction.
-                    await tx.$executeRawUnsafe(`INSERT INTO ablo_outbox (
-               id, model, entity_id, type, data,
-               correlation_id, transaction_id, occurred_at
-             ) VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8)`, `${change.correlationId}:${index}`, op.model, entityId, op.type, JSON.stringify(op.type === 'DELETE' ? null : row), change.correlationId, op.transactionId ?? null, Date.now());
-                }
-                await tx.$executeRawUnsafe(`INSERT INTO ablo_idempotency (client_tx_id, response, request_hash, expires_at)
-           VALUES ($1, $2::jsonb, $3, now() + $4::interval)`, change.correlationId, JSON.stringify(rows), requestHash, SOURCE_IDEMPOTENCY_RETENTION);
-                if (change.echo?.kind === 'postgres-wal') {
-                    // Cast the returned LSN to text. `pg_logical_emit_message` yields a
-                    // `pg_lsn`, and Prisma's driver adapter can't deserialize that OID
-                    // ("Failed to deserialize column of type 'pg_lsn'"); the value is
-                    // discarded anyway, so text is the safe carrier. (postgres.js-backed
-                    // adapters read pg_lsn as a string and don't need this.)
-                    await tx.$queryRawUnsafe(`SELECT pg_logical_emit_message(true, $1::text, $2::text)::text`, ABLO_POSTGRES_COMMIT_ECHO_PREFIX, change.echo.payload);
-                }
-                return { rows };
-            });
-        },
-        async events(cursor, limit) {
-            const after = cursor ? cursor : '0';
-            const rows = await prisma.$queryRawUnsafe(`SELECT cursor, id, model, entity_id, type, data, organization_id,
-                client_tx_id, correlation_id, transaction_id, occurred_at
-         FROM ablo_outbox WHERE cursor > $1 ORDER BY cursor ASC LIMIT $2`, after, limit);
-            const events = rows.map((r) => outboxEventSchema.parse({
-                id: r.id,
-                model: r.model,
-                entityId: r.entity_id,
-                type: r.type,
-                data: r.data ?? null,
-                organizationId: r.organization_id ?? null,
-                clientTxId: r.client_tx_id ?? null,
-                correlationId: r.correlation_id ?? null,
-                transactionId: r.transaction_id ?? null,
-                occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
-                cursor: String(r.cursor),
-            }));
-            return {
-                events,
-                nextCursor: events.at(-1)?.cursor ?? null,
-            };
-        },
-    };
-}

package/dist/source/conformance.d.ts

@@ -1,37 +0,0 @@
-/**
- * Capability-split conformance for customer-database mutation wrappers.
- *
- * `mutationConformanceChecks` covers only guarantees shared by direct and
- * endpoint: schema-mapped DML, reads, permanent scoped idempotency, canonical
- * request-hash conflicts, and concurrent replay. `endpointConformanceChecks`
- * covers the endpoint-only transactional outbox and events cursor. Direct
- * wrappers must not run (or claim) those outbox guarantees because WAL is their
- * sole source feed.
- */
-import type { DataSourceAdapter, MutationAdapter } from './adapter.js';
-import type { ChangeSet } from './contract.js';
-export type MakeMutationAdapter = () => MutationAdapter | Promise<MutationAdapter>;
-export type MakeAdapter = () => DataSourceAdapter | Promise<DataSourceAdapter>;
-export interface ConformanceCheck {
-    readonly name: string;
-    run(): Promise<void>;
-}
-export interface MutationConformanceOptions {
-    /**
-     * Add transport-required evidence without changing the shared checks. Direct
-     * wrappers use this to attach their logical marker; endpoint wrappers need no
-     * decoration.
-     */
-    readonly prepareChange?: (change: ChangeSet) => ChangeSet;
-}
-/** Guarantees shared by direct and endpoint mutation wrappers. */
-export declare function mutationConformanceChecks(make: MakeMutationAdapter, options?: MutationConformanceOptions): ConformanceCheck[];
-/** Guarantees that apply only to endpoint wrappers with an outbox/events feed. */
-export declare function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[];
-/** Compatibility name for the complete endpoint adapter suite. */
-export declare function dataSourceConformanceChecks(make: MakeAdapter): ConformanceCheck[];
-export declare function runMutationTests(make: MakeMutationAdapter, register: (name: string, fn: () => Promise<void>) => void, options?: MutationConformanceOptions): void;
-export declare function runEndpointDataSourceTests(make: MakeAdapter, register: (name: string, fn: () => Promise<void>) => void): void;
-/** Backward-compatible complete endpoint suite. */
-export declare function runDataSourceTests(make: MakeAdapter, register: (name: string, fn: () => Promise<void>) => void): void;
-export { memoryDataSource } from './adapters/memory.js';

package/dist/source/conformance.js

@@ -1,215 +0,0 @@
-/**
- * Capability-split conformance for customer-database mutation wrappers.
- *
- * `mutationConformanceChecks` covers only guarantees shared by direct and
- * endpoint: schema-mapped DML, reads, permanent scoped idempotency, canonical
- * request-hash conflicts, and concurrent replay. `endpointConformanceChecks`
- * covers the endpoint-only transactional outbox and events cursor. Direct
- * wrappers must not run (or claim) those outbox guarantees because WAL is their
- * sole source feed.
- */
-import assert from 'node:assert/strict';
-const change = (correlationId, operations, intentHash) => ({
-    correlationId,
-    operations,
-    ...(intentHash ? { intentHash } : {}),
-});
-/** Guarantees shared by direct and endpoint mutation wrappers. */
-export function mutationConformanceChecks(make, options = {}) {
-    const request = (correlationId, operations, intentHash) => {
-        const value = change(correlationId, operations, intentHash);
-        return options.prepareChange?.(value) ?? value;
-    };
-    return [
-        {
-            name: 'commit applies a CREATE and returns the canonical row',
-            run: async () => {
-                const adapter = await make();
-                const result = await adapter.commit(request('corr_create', [
-                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
-                ]));
-                assert.equal(result.rows.length, 1, 'one row returned');
-                const created = result.rows[0];
-                assert.ok(created, 'one row returned');
-                assert.equal(created.id, 't1');
-                assert.equal(created.title, 'A');
-            },
-        },
-        {
-            name: 'read load returns a committed row, and null-equivalent for an unknown id',
-            run: async () => {
-                const adapter = await make();
-                await adapter.commit(request('corr_load', [
-                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
-                ]));
-                const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
-                assert.equal(found.length, 1);
-                assert.equal(found[0]?.title, 'A');
-                const missing = await adapter.read({ kind: 'load', model: 'task', id: 'nope' });
-                assert.equal(missing.length, 0, 'unknown id reads empty');
-            },
-        },
-        {
-            name: 'read list returns committed rows',
-            run: async () => {
-                const adapter = await make();
-                await adapter.commit(request('corr_list', [
-                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
-                    { type: 'CREATE', model: 'task', id: 't2', input: { title: 'B' } },
-                ]));
-                const rows = await adapter.read({ kind: 'list', model: 'task' });
-                assert.deepEqual(rows.map((row) => row.id).sort(), ['t1', 't2']);
-            },
-        },
-        {
-            name: 'same scoped correlation and intent replays the original response without DML',
-            run: async () => {
-                const adapter = await make();
-                const commitRequest = request('corr_replay', [
-                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A', n: 1 } },
-                ]);
-                const first = await adapter.commit(commitRequest);
-                const second = await adapter.commit(commitRequest);
-                assert.deepEqual(second.rows, first.rows, 'replay returns the original rows');
-                const rows = await adapter.read({ kind: 'list', model: 'task' });
-                assert.equal(rows.length, 1, 'no duplicate row');
-            },
-        },
-        {
-            name: 'same scoped correlation with a different canonical intent rejects',
-            run: async () => {
-                const adapter = await make();
-                await adapter.commit(request('corr_conflict', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }], 'a'.repeat(64)));
-                await assert.rejects(adapter.commit(request('corr_conflict', [{ type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } }], 'b'.repeat(64))), (error) => typeof error === 'object' &&
-                    error !== null &&
-                    'code' in error &&
-                    error.code === 'idempotency_conflict');
-            },
-        },
-        {
-            name: 'concurrent identical requests apply once and replay one response',
-            run: async () => {
-                const adapter = await make();
-                const commitRequest = request('corr_concurrent', [
-                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
-                ]);
-                const [first, second] = await Promise.all([
-                    adapter.commit(commitRequest),
-                    adapter.commit(commitRequest),
-                ]);
-                assert.deepEqual(second.rows, first.rows);
-                const rows = await adapter.read({ kind: 'list', model: 'task' });
-                assert.equal(rows.length, 1, 'concurrent retries produced one row');
-            },
-        },
-        {
-            name: 'a later mutation under a new scoped correlation is applied',
-            run: async () => {
-                const adapter = await make();
-                await adapter.commit(request('corr_create_2', [
-                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
-                ]));
-                await adapter.commit(request('corr_update_2', [
-                    { type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } },
-                ]));
-                const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
-                assert.equal(found[0]?.title, 'B', 'update applied');
-            },
-        },
-    ];
-}
-/** Guarantees that apply only to endpoint wrappers with an outbox/events feed. */
-export function endpointConformanceChecks(make) {
-    return [
-        {
-            name: 'endpoint replay does not append its correlated outbox event twice',
-            run: async () => {
-                const adapter = await make();
-                assert.equal(adapter.capabilities.outboxEvents, true);
-                const request = change('corr_outbox_replay', [
-                    {
-                        type: 'CREATE',
-                        model: 'task',
-                        id: 't1',
-                        input: { title: 'A' },
-                        transactionId: 'op_outbox_replay',
-                    },
-                ]);
-                await adapter.commit(request);
-                await adapter.commit(request);
-                const page = await adapter.events(null, 100);
-                assert.equal(page.events.filter((event) => event.correlationId === 'corr_outbox_replay').length, 1);
-            },
-        },
-        {
-            name: 'endpoint outbox exposes explicit correlation and operation identity',
-            run: async () => {
-                const adapter = await make();
-                assert.equal(adapter.capabilities.outboxEvents, true);
-                await adapter.commit(change('corr_event', [
-                    {
-                        type: 'CREATE',
-                        model: 'task',
-                        id: 't1',
-                        input: { title: 'A' },
-                        transactionId: 'op_event',
-                    },
-                ]));
-                const page = await adapter.events(null, 100);
-                const event = page.events.find((candidate) => candidate.entityId === 't1');
-                assert.ok(event, 'event for the committed row');
-                assert.equal(event.model, 'task');
-                assert.equal(event.type, 'CREATE');
-                assert.equal(event.correlationId, 'corr_event');
-                assert.equal(event.transactionId, 'op_event');
-                assert.equal(event.clientTxId ?? null, null, 'legacy echo identity stays empty');
-            },
-        },
-        {
-            name: 'endpoint events cursor advances and never re-delivers a page',
-            run: async () => {
-                const adapter = await make();
-                await adapter.commit(change('corr_page_a', [
-                    { type: 'CREATE', model: 'task', id: 't1', input: {} },
-                ]));
-                await adapter.commit(change('corr_page_b', [
-                    { type: 'CREATE', model: 'task', id: 't2', input: {} },
-                ]));
-                const first = await adapter.events(null, 1);
-                assert.equal(first.events.length, 1, 'respects limit');
-                assert.ok(first.nextCursor, 'returns a cursor');
-                const second = await adapter.events(first.nextCursor, 100);
-                const firstIds = new Set(first.events.map((event) => event.id));
-                for (const event of second.events) {
-                    assert.ok(!firstIds.has(event.id), `event ${event.id} re-delivered across cursor`);
-                }
-                const drained = await adapter.events(second.nextCursor ?? first.nextCursor, 100);
-                assert.equal(drained.events.length, 0, 'fully drained');
-            },
-        },
-    ];
-}
-/** Compatibility name for the complete endpoint adapter suite. */
-export function dataSourceConformanceChecks(make) {
-    return [
-        ...mutationConformanceChecks(make),
-        ...endpointConformanceChecks(make),
-    ];
-}
-export function runMutationTests(make, register, options = {}) {
-    for (const check of mutationConformanceChecks(make, options)) {
-        register(check.name, check.run);
-    }
-}
-export function runEndpointDataSourceTests(make, register) {
-    for (const check of endpointConformanceChecks(make)) {
-        register(check.name, check.run);
-    }
-}
-/** Backward-compatible complete endpoint suite. */
-export function runDataSourceTests(make, register) {
-    for (const check of dataSourceConformanceChecks(make)) {
-        register(check.name, check.run);
-    }
-}
-export { memoryDataSource } from './adapters/memory.js';

package/dist/source/connector.d.ts

@@ -1,95 +0,0 @@
-/**
- * Opens the connector's side of the Data Source reverse channel. You run this
- * process next to your database; it dials an outbound WebSocket to Ablo and serves
- * the load, list, and commit requests over that socket, so a handler with no
- * public URL never needs to receive inbound webhooks. It is the counterpart to
- * `createPushQueue`, which gives the outbound events feed the same treatment, and
- * it speaks the frames defined in `connectorProtocol.ts`.
- *
- * The connector reimplements none of the handler logic. It wraps the same
- * `(request: Request) => Promise<Response>` your deployed route already uses:
- *
- *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
- *   import { sourceOptions } from './ablo.source'; // shared with route.ts
- *
- *   const connector = createSourceConnector({
- *     apiKey: process.env.ABLO_API_KEY!,
- *     handler: dataSource(sourceOptions),
- *   });
- *   await connector.run(controller.signal);
- *
- * Each incoming `request` frame is replayed into a `Request` that carries the
- * original signature headers, so the handler verifies it through the same
- * `verifyAbloSourceRequest` it uses on the webhook path. The transport changes;
- * the trust model does not.
- */
-/**
- * The reconnect backoff, in milliseconds, indexed by the number of consecutive
- * failed connect attempts. A long-lived control socket should recover quickly and
- * then settle at a steady interval, so this is a short curve that caps rather than
- * growing without bound. The final entry repeats for any further attempts, and a
- * connection that reaches `ready` resets the count to zero.
- */
-export declare const DEFAULT_RECONNECT_SCHEDULE: readonly number[];
-/**
- * The minimal WebSocket surface the connector needs, matching the standard
- * `globalThis.WebSocket` API that browsers and current Node versions provide. The
- * `ws` package's default export also satisfies it. Supply your own implementation
- * to substitute a fake in tests.
- */
-export interface ConnectorWebSocket {
-    send(data: string): void;
-    close(code?: number, reason?: string): void;
-    readonly readyState: number;
-    addEventListener(type: 'open', listener: () => void): void;
-    addEventListener(type: 'message', listener: (event: {
-        data: unknown;
-    }) => void): void;
-    addEventListener(type: 'close', listener: (event: {
-        code?: number;
-        reason?: string;
-    }) => void): void;
-    addEventListener(type: 'error', listener: (event: unknown) => void): void;
-}
-export type ConnectorWebSocketFactory = (url: string, protocols: readonly string[]) => ConnectorWebSocket;
-/** Lifecycle of the connector's socket, surfaced via `onStatus`. */
-export type ConnectorStatus = 'connecting' | 'ready' | 'disconnected';
-export interface SourceConnectorOptions {
-    /**
-     * Your Ablo project API key. A test key (`sk_test_*`) works by default for local
-     * development and sandboxes; a live key (`sk_live_*`) is accepted only once the
-     * source has opted the reverse channel in for production use.
-     */
-    readonly apiKey: string;
-    /**
-     * The Data Source handler to serve, as returned by `dataSource(options)`.
-     * The connector feeds it each request and relays the response back untouched;
-     * it never inspects or alters either one.
-     */
-    readonly handler: (request: Request) => Promise<Response>;
-    /** The Ablo base URL to dial. Defaults to `https://api.abloatai.com`. */
-    readonly baseURL?: string;
-    /** Inject a WebSocket implementation. Default `globalThis.WebSocket`. */
-    readonly webSocket?: ConnectorWebSocketFactory;
-    /** Override reconnect backoff. Default `DEFAULT_RECONNECT_SCHEDULE`. */
-    readonly reconnectSchedule?: readonly number[];
-    /** Random jitter on reconnect delays. Default ±10%. Set 0 to disable. */
-    readonly jitter?: number;
-    /** Advisory client id sent in the `register` frame for server-side logs. */
-    readonly client?: string;
-    /** Pluggable clock (tests). */
-    readonly now?: () => number;
-    /** Observe connection lifecycle transitions. */
-    readonly onStatus?: (status: ConnectorStatus) => void;
-    /** Observe non-fatal errors (decode failures, handler throws, socket errors). */
-    readonly onError?: (error: unknown) => void;
-}
-export interface SourceConnector {
-    /**
-     * Runs the connect, serve, and reconnect loop until `signal` aborts, then
-     * resolves. It rejects only on a fatal condition that cannot be retried, such as
-     * no WebSocket implementation being available.
-     */
-    run(signal: AbortSignal): Promise<void>;
-}
-export declare function createSourceConnector(options: SourceConnectorOptions): SourceConnector;