@volter/twin-planetscale 0.1.0

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

@@ -0,0 +1,126 @@
+import { SqlError, type Database, type QueryOutcome, type RowRec, type SessionVars, type TableDef, type Write } from './planetscale-sql.js';
+import { type SqlPlan } from './planetscale-deploy.js';
+export declare const SERVICE = "planetscale";
+export declare const PLANETSCALE_RESOURCE_TYPES: readonly ["table", "row", "_session", "_backup", "_branch_table", "_branch_row"];
+export type PlanetscaleResourceType = (typeof PLANETSCALE_RESOURCE_TYPES)[number];
+/** The default schema name a twin branch presents. Overridable per server, like the branch. */
+export declare const DEFAULT_DATABASE = "twin";
+export declare const DEFAULT_BRANCH = "main";
+export type SessionState = {
+    id: string;
+    inTransaction: boolean;
+    /** writes buffered by an open transaction, in order. Empty outside a transaction. */
+    pending: Write[];
+    pendingPlans: SqlPlan[];
+    /** row-lock keys a locking read (`FOR UPDATE`/`FOR SHARE`) took in the open transaction. */
+    locks?: string[];
+    /** The open transaction is READ ONLY (`START TRANSACTION READ ONLY`, or SET TRANSACTION's). */
+    readOnly?: boolean;
+    /** `SET SESSION TRANSACTION READ ONLY|READ WRITE`: the access mode of every later transaction. */
+    sessionAccess?: 'READ WRITE' | 'READ ONLY';
+    /** `SET TRANSACTION READ ONLY|READ WRITE`: the access mode of the NEXT transaction only. */
+    nextAccess?: 'READ WRITE' | 'READ ONLY';
+    closed: boolean;
+    /** the branch scope the session was opened on; absent on `main` */
+    scope?: string;
+};
+type Loaded = {
+    db: Database;
+    /** the sessions of the scope loaded (of `main` when none) */
+    sessions: Map<string, SessionState>;
+    /** every session id of every scope, which a new session's id must not repeat */
+    sessionIds: string[];
+    /** subject id → the highest `_rev` ever written for it, INCLUDING deleted subjects. */
+    revs: Map<string, number>;
+};
+/** A scope that is `main` (or none) is the World's image; any other names a branch's own subjects. */
+export declare const scopeOf: (database: string, branch: string) => string | undefined;
+/** The action log folded into a `Database` image plus the session book. The maps (tables, rows, sessions) are the
+ *  caller's own; the row arrays, row records, table definitions and `sessionIds` are shared and must not be changed in
+ *  place (replace an array to change it, as `applyWritesToImage` does). */
+export declare function loadState(root: string | undefined, databaseName: string, scope?: string): Loaded;
+/** Apply a buffered write list to an in-memory image (the transaction overlay). */
+export declare function applyWritesToImage(db: Database, writes: Write[]): void;
+export type ExecuteContext = {
+    root?: string;
+    occurredAt: string;
+    /** the session variables the client's session carries (planetscale-wire.ts, sessionVarsOf) */
+    vars?: SessionVars;
+    readOnly?: boolean;
+    database?: string;
+    branch?: string;
+    /** the branch scope the statement acts on (scopeOf); absent on `main` */
+    scope?: string;
+};
+export type ExecuteResult = {
+    outcome: QueryOutcome;
+    /** the session as it stands AFTER the statement — the caller echoes it back on the wire. */
+    session: SessionState;
+};
+/** Mint a session id deterministically from the state that already exists — never entropy, never a
+ *  row count. The serve path must be a pure function of (request, stored state), so a session id is
+ *  derived from the ids already present rather than from `crypto.randomUUID()`. */
+export declare function mintSessionId(existing: Iterable<string>, occurredAt: string): string;
+/** Open a new session. */
+export declare const createSession: (ctx: ExecuteContext) => Promise<SessionState>;
+/** Close a session, discarding any uncommitted transaction. */
+export declare const closeSession: (ctx: ExecuteContext, id: string) => Promise<boolean>;
+/** Execute ONE statement in the named session. A statement blocked by another transaction's row
+ *  locks waits OUTSIDE the serialization gate, so the holder's COMMIT can run, then re-executes. */
+export declare function executeSql(ctx: ExecuteContext, sql: string, incomingSessionId: string | null): Promise<ExecuteResult>;
+/**
+ * The CURRENT state of one session, or undefined. Read by the request handler's error path: a
+ * statement that FAILS inside an open transaction must still echo `inTransaction: true`, because
+ * MySQL does not end a transaction on a failed statement (§9 round one, finding 10 — the handler
+ * used to answer a flat `false` and tell the caller the transaction had ended when it had not).
+ */
+export declare function sessionState(root: string | undefined, id: string, databaseName?: string, scope?: string): SessionState | undefined;
+/** Read-only projection helper — used by the connector's push-free inspection and by tests. */
+export declare function readDatabase(root: string | undefined, databaseName?: string, scope?: string): Database;
+/** The named projections this pack serves through the store door (planetscale-server.ts). */
+export declare const STORE_NAMES: readonly ["tables", "rows"];
+export type StoreName = (typeof STORE_NAMES)[number];
+/**
+ * THE STORE DOOR projection (`GET /twin/store/<tables|rows>`, the twin programming model's named
+ * read-only read over stored state).
+ *
+ * The psdb wire is Connect-JSON: EVERY call, `Execute` included, is a POST, and the handler
+ * refuses a GET on the RPC path before it authenticates (Connect unary is POST-only, which is
+ * vendor-faithful). So a `SELECT` — the vendor's own read — cannot be a GET, and nothing in the
+ * vendor surface observes stored state with one. This is that observation: a pure, ordered fold
+ * of the same image `Execute` runs against, with the engine's internal `rowid` included because
+ * it is the row identity the projection is keyed on.
+ *
+ * `Map` iteration order is insertion order, which is a function of the log rather than of the
+ * state, so both projections are SORTED — by table key, and within a table by rowid.
+ */
+export declare function planetscaleStore(name: StoreName, root: string | undefined, databaseName?: string): unknown;
+export { SqlError };
+/** Drop every table of the branch, each in a session of its own that is closed after it: what deleting the database
+ *  does to its data (the management lane's delete_database; "Remove all data and backups permanently"). */
+export declare function dropAllTables(ctx: ExecuteContext): Promise<void>;
+/** A branch's image as a backup or a new branch carries it: its tables, and its rows by table. */
+export type ScopeImage = {
+    tables: TableDef[];
+    rows: Array<{
+        table: string;
+        rows: RowRec[];
+    }>;
+};
+/** The image of a scope (`main` when none), sorted as the store door sorts it. */
+export declare function scopeImage(root: string | undefined, scope?: string): ScopeImage;
+/**
+ * Make a branch scope hold `image` (its tables, and its rows when a backup is restored): what creating a branch does
+ * ("the schema of the source branch is copied to the new branch", planetscale.com/docs/vitess/schema-changes/branching)
+ * and what restoring a backup into a new branch does (the spec's `create_branch.backup_id`: "restores the backup's schema
+ * and data"). One `branch.seed` action; nothing of `main` is touched.
+ */
+export declare function seedScope(ctx: {
+    root?: string;
+    occurredAt: string;
+}, scope: string, image: ScopeImage): Promise<void>;
+/** Drop every table of a branch scope with its rows, in one action: what deleting the branch does to its data. */
+export declare function dropScope(ctx: {
+    root?: string;
+    occurredAt: string;
+}, scope: string): Promise<void>;