@volter/twin-planetscale 0.1.0

package/dist/src/planetscale-connector.d.ts

@@ -0,0 +1,150 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { type PlanetscaleBudgetedOptions } from './planetscale-budget.js';
+import { type Cell, type ColumnDef, type TableDef } from './planetscale-sql.js';
+export { pulledRowId, quoteIdent, quoteSqlLiteral } from './planetscale-row.js';
+export type { PlanetscaleBudgetedOptions };
+/**
+ * The subset of a real PlanetScale client this connector calls.
+ *
+ * A `@planetscale/database` `Client`/`Connection` satisfies it structurally. Pulls require
+ * execute; a missing executor is a failure, never evidence of an empty database.
+ */
+export interface PlanetscaleLikeClient {
+    execute?: (query: string, args?: unknown, options?: unknown) => Promise<PlanetscaleExecutedQuery>;
+    transaction?: <T>(fn: (tx: unknown) => Promise<T>) => Promise<T>;
+    refresh?: () => Promise<void>;
+}
+/** `ExecutedQuery` as the real client returns it (dist/index.d.ts). Only what this connector reads. */
+export type PlanetscaleExecutedQuery = {
+    rows: Array<Record<string, unknown>>;
+    fields?: Array<{
+        name: string;
+        type?: string;
+        columnType?: string | null;
+        flags?: number | null;
+        charset?: number | null;
+        columnLength?: number | null;
+    }>;
+    rowsAffected?: number;
+    insertId?: string;
+};
+/** One table observed on the real database, already in this twin's storage shape. */
+export type PlanetscaleRealTable = {
+    name: string;
+    columns: ColumnDef[];
+    primaryKey: string[];
+    uniques: Array<{
+        name: string;
+        columns: string[];
+    }>;
+    autoIncrement: number;
+    rows: Array<{
+        rowid: number;
+        cells: Record<string, Cell>;
+    }>;
+};
+/**
+ * A `DESCRIBE <table>` row → a `ColumnDef`.
+ *
+ * MySQL's `DESCRIBE` output is the schema as the SERVER renders it: `Type` is the full column type
+ * (`varchar(255)`, `bigint unsigned`), `Null` is `YES`/`NO`, `Key` is `PRI`/`UNI`/`MUL`/``, `Default`
+ * is the literal or NULL, and `Extra` carries `auto_increment`. Every field of `ColumnDef` is
+ * derivable from those five, which is why the pull needs no information_schema query.
+ */
+export declare function mapDescribeRow(row: Record<string, unknown>): ColumnDef;
+/** A real table → the kernel `table` resource. */
+export declare function mapTable(real: PlanetscaleRealTable): SyncResource;
+/** Vendor cells are nested to avoid reserved resource keys. Local write ordinals are
+ *  deliberately absent: observation must compare vendor facts, not local bookkeeping. */
+export declare function mapRow(table: string, rowid: number, cells: Record<string, Cell>): SyncResource;
+/** Normalize a value the real client handed back into this twin's text-cell encoding. */
+export declare function encodeCellValue(value: unknown): Cell;
+/**
+ * MySQL string-literal quoting, for the statements this connector BUILDS.
+ *
+ * Deliberately a local implementation rather than importing the SDK's `format`: this pack must not
+ * depend on the vendor SDK at runtime (it is a devDependency), and the escape set here is the same
+ * one `@planetscale/database`'s `dist/sanitization.js` uses — \0 \b \n \r \t \x1a \\ " '.
+ */
+/** MySQL identifier quoting — a backtick inside an identifier is doubled. */
+export type PlanetscalePullOptions = {
+    /** Only these tables. Omit to discover them with `SHOW TABLES`. */
+    tables?: string[];
+    /** Maximum returned rows per page (1–10,000), default 500. Not a billed-rows guarantee. */
+    rowLimit?: number;
+    /** Maximum pages per table (1–100), default 10. A full last page remains partial. */
+    maxPages?: number;
+    /** Maximum missing-row point checks per refresh (1–1,000), default 100. */
+    maxMissingChecks?: number;
+} & PlanetscaleBudgetedOptions;
+export type PlanetscalePullReport = {
+    resources: SyncResource[];
+    completeTables: string[];
+    partialTables: string[];
+};
+export type PlanetscaleRefreshReport = Omit<PlanetscalePullReport, 'resources'> & {
+    observed: number;
+    deltasAppended: number;
+    removed: number;
+};
+/** Discover the real database's table names. */
+export declare function pullPlanetscaleTables(rawClient: PlanetscaleLikeClient, opts?: PlanetscaleBudgetedOptions): Promise<string[]>;
+/** Compatibility resource-only pull. Use pullPlanetscaleSnapshot for completion metadata. */
+export declare function pullPlanetscaleDatabase(rawClient: PlanetscaleLikeClient, opts?: PlanetscalePullOptions): Promise<SyncResource[]>;
+/** Bounded scan. A short page proves that this traversal ended; it is not a global snapshot. */
+export declare function pullPlanetscaleSnapshot(rawClient: PlanetscaleLikeClient, opts?: PlanetscalePullOptions): Promise<PlanetscalePullReport>;
+/**
+ * Pull the real database and fold it into the twin through the kernel observation path. Returns `{observed, deltasAppended}` — a re-pull of identical state appends ZERO deltas,
+ * which is what makes the pull idempotent.
+ */
+export declare function syncPlanetscaleFromReal(rawClient: PlanetscaleLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+} & PlanetscalePullOptions): Promise<PlanetscaleRefreshReport>;
+/** `now`, forced strictly increasing within this process — see `syncPlanetscaleFromReal`. */
+export declare function pollTimestamp(): string;
+/** Apply captured row changes as one guarded vendor transaction. The transaction reservation
+ *  covers BEGIN, its callback, COMMIT and rollback, so exhausted budget cannot strand an open
+ *  transaction halfway through cleanup. Known row plans reserve all row and lifecycle calls. */
+export declare function applyPlanetscaleRows(rawClient: PlanetscaleLikeClient, plan: unknown, opts?: PlanetscaleBudgetedOptions): Promise<string[]>;
+/** Compatibility entry point over the same captured plan as the head's performer. */
+export declare function pushPlanetscaleAction(rawClient: PlanetscaleLikeClient, action: {
+    id: string;
+    operation?: string;
+    subjectType?: string;
+    subjectId?: string;
+    fields?: Record<string, unknown>;
+    input?: Record<string, unknown>;
+}, opts?: {
+    root?: string;
+    occurredAt?: string;
+} & PlanetscaleBudgetedOptions): Promise<{
+    pushed: boolean;
+    statement: string;
+}>;
+export declare function pushPlanetscaleActions(rawClient: PlanetscaleLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+} & PlanetscaleBudgetedOptions): Promise<{
+    pushed: number;
+}>;
+export type { TableDef };
+/**
+ * A `PlanetscaleLikeClient` over the kernel's executor.
+ *
+ * PlanetScale's serverless driver speaks CONNECT RPC over unary JSON POSTs to
+ * `psdb.v1alpha1.Database` — `CreateSession` then `Execute` — so a session is established once and
+ * carried on every query after it, exactly as `@planetscale/database` does. At a REAL boundary the
+ * kernel sets the sealed credential over these headers (executor.ts); at the twin's own wire any
+ * credential is one.
+ */
+export declare function planetscaleClientOver(execute: RemoteExecute): PlanetscaleLikeClient;
+/** The refresh adapter: PlanetScale enumerates through SQL itself (`SHOW TABLES`, then each table),
+ *  with explicit per-table completion from the bounded scan. */
+export declare function syncPlanetscaleFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+} & PlanetscalePullOptions): Promise<PlanetscaleRefreshReport>;
+/** The head performs the captured row plan; query results never become resource fields. */
+export declare function performPlanetscaleAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext, opts?: PlanetscaleBudgetedOptions): Promise<PushOutcome>;