@lunora/hyperdrive 1.0.0-alpha.22 → 1.0.0-alpha.221

package/dist/global.d.ts

@@ -1,47 +1,178 @@
-import { DatabaseWriterLike } from '@lunora/do';
-import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
-/** Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg` result). */
-interface RowClient {
-  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
-}
-/** Minimal `mysql2/promise` connection/pool surface — `execute` resolves to `[rows | ResultSetHeader, fields]`. */
-interface Mysql2Execute {
-  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
-}
 /**
-* Wrap a Postgres row-client (from `@lunora/hyperdrive`'s `fromPostgresJs` /
-* `fromNodePg`) as a {@link SqlExec}. The core already renders `$N` placeholders
-* for Postgres, so `all`/`run` forward verbatim. Postgres uses `RETURNING` for
-* OCC (read via `all`), so `run` reports no affected-row count.
-*/
+ * `@lunora/hyperdrive/global` — a Postgres/MySQL database reached through
+ * Cloudflare Hyperdrive (PlanetScale, Neon, RDS, …) as a **first-class,
+ * reactive** `.global()` storage backend for Lunora, alongside D1.
+ *
+ * Unlike the package's `ctx.sql` surface (an action-only, non-reactive escape
+ * hatch for an external DB), this makes Lunora the **owner** of the schema:
+ * `.global()` tables get a real column-per-field layout and all writes route
+ * through the shared store core (`createSqlCtxDb` from `@lunora/sql-store`) with
+ * a Postgres or MySQL {@link postgresDialect}/{@link mysqlDialect} and a
+ * Hyperdrive-backed {@link SqlExec}. The returned `DatabaseWriterLike` is
+ * injected as `globalDb` into `createShardCtxDb`, whose broadcast hook drives
+ * live queries — so subscriptions stay reactive with zero extra wiring,
+ * identical to D1.
+ *
+ * Drivers (`postgres`/`pg`/`mysql2`) are optional peer deps — bring your own,
+ * constructed from the `HYPERDRIVE` binding's connection string. The binding is
+ * reachable from inside the Durable Object that hosts the writer; cache the
+ * driver on the DO instance and rebuild it lazily after hibernation.
+ *
+ * **MySQL connections must enable `CLIENT_FOUND_ROWS`** (mysql2:
+ * `createPool({ flags: ["FOUND_ROWS"] })`) so the affected-rows OCC guard sees
+ * matched (not changed) rows — see {@link buildMysqlExec}.
+ *
+ * **The Hyperdrive config must have query caching disabled**
+ * (`wrangler hyperdrive create … --caching-disabled`). Hyperdrive caches reads by
+ * default and a write does not invalidate them, so OCC re-reads, change-log polls
+ * and live-query re-runs would read rows up to `max_age + stale_while_revalidate`
+ * old.
+ */
+import { SchemaLike, ImportConflictMode, CdcChange, DatabaseWriterLike } from '@lunora/shard-engine';
+import { SqlExec, SqlDialect, SqlCtxDbOptions, FacetGlobalColumnOptions, GlobalFacetResult, GlobalTableInfo, ReadGlobalTablePageOptions, GlobalTablePage, ExportRow, ImportResult } from '@lunora/sql-store';
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-DKB5Qb1Z.js";
+import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
+/**
+ * Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg`
+ * result). Aliases {@link SqlClient} — the exec-facing name is kept so call sites read
+ * intent, but the shape is the single source of truth in `./types` (no drift).
+ */
+type RowClient = SqlClient;
+/**
+ * Minimal `mysql2/promise` connection/pool surface — `query` resolves to
+ * `[rows | ResultSetHeader, fields]`. Aliases {@link Mysql2Like} so the /global
+ * entry's driver surface can never drift from the main entry's, widened with the
+ * (optional, structural) shape {@link assertFoundRows}'s `CLIENT_FOUND_ROWS`
+ * probe reads.
+ *
+ * A real `mysql2/promise` connection/pool exposes the merged client-flags
+ * bitmask synchronously, but at two different depths depending on which one it
+ * is, and NEITHER is in `mysql2`'s own `.d.ts` — its `Pool extends Connection`
+ * signature claims a top-level `config`, but at runtime a `mysql2/promise`
+ * `Pool` has none; the real value lives one level down, on the core pool it
+ * wraps:
+ *
+ * - a single `Connection`/`PoolConnection` → `connection.config.clientFlags`
+ * - a `Pool` (the `createPool({ flags: ["FOUND_ROWS"] })` example above) →
+ * `pool.pool.config.connectionConfig.clientFlags`
+ *
+ * Because those paths are undocumented driver internals, `global-dialect.test.ts`
+ * pins them against a REAL `mysql2` pool (built without connecting) rather than
+ * only against hand-written doubles — if a `mysql2` release relocates them, the
+ * probe would otherwise degrade silently to the warn branch and the OCC guard
+ * would go unchecked.
+ *
+ * The probe fields are typed `unknown` publicly: the paths are not in `mysql2`'s
+ * typings, so spelling them out made a real `createPool(...)` fail to type-check
+ * (TS2345, weak-type mismatch on `config`). {@link readMysqlClientFlags} reads
+ * them through the internal `FlagProbeShape` instead, and a minimal test double
+ * (only `query`) resolves to "undeterminable" rather than a `TypeError`.
+ */
+type Mysql2Client = Mysql2Like & {
+  config?: unknown;
+  pool?: unknown;
+};
+/**
+ * Wrap a Postgres row-client (from `@lunora/hyperdrive`'s `fromPostgresJs` /
+ * `fromNodePg`) as a {@link SqlExec}. The core already renders `$N` placeholders
+ * for Postgres, so `all`/`run` forward verbatim. Postgres uses `RETURNING` for
+ * OCC (read via `all`), so `run` reports no affected-row count.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`) over `client`
+ * rather than awaiting each `query` call in turn — `RowClient` only exposes a
+ * single-statement `query`, so there is no wire-level multi-statement command
+ * to reach for. When `client` is backed by a pool (the common production
+ * shape), this genuinely spreads the statements across multiple physical
+ * connections instead of serializing one full round trip at a time; against a
+ * single connection it still removes the sequential *await*, though the
+ * underlying driver may itself queue the sends. Either way it stays
+ * non-atomic, at-least-once, and unordered between elements, same as the
+ * sequential fallback minus the ordering — safe only for statements whose
+ * effects don't depend on each other, which is what every current caller
+ * batches (distinct-keyed companion rows).
+ *
+ * `transaction` is present when `client` has one (`fromPostgresJs`): the
+ * store's row + companion writes then run on one reserved connection and
+ * commit together.
+ */
 declare const buildPgExec: (client: RowClient) => SqlExec;
 /**
-* Wrap a `mysql2/promise` connection/pool as a {@link SqlExec}. The core already
-* renders backtick identifiers and `?` placeholders for MySQL, so `all`/`run`
-* forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
-* for the store's affected-rows OCC guard.
-*
-* **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
-* (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
-* counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
-* same values reports 0 and the OCC guard raises a spurious conflict.
-*/
-declare const buildMysqlExec: (connection: Mysql2Execute) => SqlExec;
+ * Wrap a `mysql2/promise` connection/pool as a {@link SqlExec}. The core already
+ * renders backtick identifiers and `?` placeholders for MySQL, so `all`/`run`
+ * forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
+ * for the store's affected-rows OCC guard.
+ *
+ * Statements go over as text with client-side escaping, so the server must not
+ * run with `NO_BACKSLASH_ESCAPES` (see {@link Mysql2Like}).
+ *
+ * **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
+ * (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
+ * counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
+ * same values reports 0 and the OCC guard raises a spurious conflict. Verified
+ * once here at construction — see {@link assertFoundRows} — never per statement.
+ *
+ * Given a **pool** (anything with `getConnection`), `transaction` takes one
+ * connection for the store's row + companion writes, so they commit together.
+ * A single connection gets no `transaction`: other writers' statements would
+ * land inside an open one, so its companions commit one statement at a time.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`), same
+ * rationale as {@link buildPgExec}'s `batch` — `Mysql2Like` only exposes a
+ * single-statement `query`, so this is "spread across a pool's connections"
+ * rather than one wire-level multi-statement command; still non-atomic,
+ * at-least-once, and unordered between elements, safe only for statements
+ * with no cross-effect (what every current caller batches).
+ */
+declare const buildMysqlExec: (connection: Mysql2Client) => SqlExec;
 /**
-* **Postgres** dialect. Differs from SQLite only in column types
-* (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
-* probe, and unique-violation detection (SQLSTATE `23505`).
-*/
+ * **Postgres** dialect. Differs from SQLite only in column types
+ * (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
+ * probe, and unique-violation detection (SQLSTATE `23505`).
+ */
 declare const postgresDialect: SqlDialect;
 /**
-* **MySQL** dialect. Diverges in: **no `RETURNING`** (the store's OCC falls back
-* to affected-rows — which requires the connection's `CLIENT_FOUND_ROWS` flag so
-* a no-op update still reports a matched row, see `buildMysqlExec`); bounded
-* `VARCHAR` keys (TEXT can't be a primary key / unindexed); a TEXT/BLOB index key
-* prefix; and `ER_DUP_ENTRY` (errno 1062) unique violations. (Drizzle's MySQL
-* dialect supplies the backtick identifiers + `ON DUPLICATE KEY` upserts.)
-*/
+ * **MySQL** dialect. Diverges in: **no `RETURNING`** (the store's OCC falls back
+ * to affected-rows — which requires the connection's `CLIENT_FOUND_ROWS` flag so
+ * a no-op update still reports a matched row, see `buildMysqlExec`); bounded
+ * `VARCHAR` keys (TEXT can't be a primary key / unindexed); a TEXT/BLOB index key
+ * prefix; and `ER_DUP_ENTRY` (errno 1062) unique violations. (Drizzle's MySQL
+ * dialect supplies the backtick identifiers + `ON DUPLICATE KEY` upserts.)
+ */
 declare const mysqlDialect: SqlDialect;
+/** Options for {@link createPgVectorIndex}. */
+interface PgVectorIndexOptions {
+  /** Postgres client — the same `SqlClient` the Hyperdrive global store takes. */
+  client: SqlClient;
+  /**
+   * Vector width. Must match the embedder's output and the `dimensions` on the
+   * schema's `.vectorize(...)`; Postgres enforces it per row, so a mismatch
+   * surfaces as a write error rather than silently bad neighbours.
+   */
+  dimensions: number;
+  /** Distance metric. Defaults to `"cosine"`, matching the common embedding case. */
+  metric?: VectorMetric;
+  /**
+   * Names the backing table (`__vec_<name>`), derived rather than configurable —
+   * a second name for one index is a way to lose data, not a feature.
+   *
+   * This is NOT required to equal the key in the shard's `vectors` map, and often
+   * cannot: that key mirrors the schema's `.vectorize({ index })`, which may carry
+   * hyphens (`"docs-body"`), while this must be a bare SQL identifier. Keep it
+   * stable — changing it points the index at a different, empty table.
+   */
+  name: string;
+}
+/**
+ * Build a `pgvector`-backed vector index that satisfies {@link VectorizeIndexLike}.
+ *
+ * Requires the `vector` extension to be installable by the connecting role
+ * (`CREATE EXTENSION IF NOT EXISTS vector`). On a managed Postgres where the
+ * role cannot create extensions, install it once out-of-band; the statement is
+ * then a no-op.
+ * @param options See {@link PgVectorIndexOptions}.
+ * @returns An index object the shard's `vectors` map accepts as-is.
+ */
+declare const createPgVectorIndex: (options: PgVectorIndexOptions) => VectorizeIndexLike;
 /** Which engine a Hyperdrive-backed `.global()` store targets. */
 type HyperdriveEngine = "mysql" | "postgres";
 /** Options for {@link createHyperdriveGlobalCtxDb}: the store options minus `exec`/`dialect`, plus the engine and a built `SqlExec`. */
@@ -52,18 +183,83 @@ interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dial
   exec: SqlExec;
 }
 /**
-* Build a reactive `.global()` writer backed by a Hyperdrive-reachable
-* Postgres/MySQL database. Pass a built {@link SqlExec} (via {@link buildPgExec}/
-* {@link buildMysqlExec}) and the matching `engine`; everything else mirrors the
-* D1 store options.
-*/
-declare const createHyperdriveGlobalCtxDb: ({
-  engine,
-  exec,
-  ...rest
-}: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+ * Build a reactive `.global()` writer backed by a Hyperdrive-reachable
+ * Postgres/MySQL database. Pass a built {@link SqlExec} (via {@link buildPgExec}/
+ * {@link buildMysqlExec}) and the matching `engine`; everything else mirrors the
+ * D1 store options.
+ */
+declare const createHyperdriveGlobalCtxDb: ({ engine, exec, ...rest }: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+/** Options for {@link exportHyperdriveGlobalRows}. */
+interface ExportHyperdriveGlobalRowsOptions {
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+  /** Table allowlist; empty or absent exports every `.global()` table. */
+  tables?: ReadonlyArray<string>;
+}
+/**
+ * The admin export's global plane on Hyperdrive: yield every requested
+ * `.global()` table's rows, keyset-paged. Provisions the schema's tables first,
+ * so a table that was never written exports as empty instead of failing.
+ */
+declare const exportHyperdriveGlobalRows: ({ engine, exec, schema, tables }: ExportHyperdriveGlobalRowsOptions) => AsyncGenerator<ExportRow, void, undefined>;
+/** Options for {@link importHyperdriveGlobalRows}. */
+interface ImportHyperdriveGlobalRowsOptions {
+  /** Append each insert to the global CDC log, like any other write — the app's own `cdc` setting. */
+  cdc: boolean;
+  /** Validate and report shape errors only; nothing is probed or written. */
+  dryRun?: boolean;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  /** `"replace"` overwrites a row whose `_id` already exists; `"skip"` (the default) counts it as a conflict. */
+  onConflict?: ImportConflictMode;
+  rows: ReadonlyArray<ExportRow>;
+  schema: SchemaLike;
+  startLine?: number;
+}
+/**
+ * The admin import's global plane on Hyperdrive: insert snapshot rows through
+ * the same store core `.global()` writes use. A row whose `_id` already exists
+ * is a conflict left unchanged, unless `onConflict` is `"replace"`.
+ */
+declare const importHyperdriveGlobalRows: ({ cdc, dryRun, engine, exec, onConflict, rows, schema, startLine }: ImportHyperdriveGlobalRowsOptions) => Promise<ImportResult>;
 /** Convenience: a **Postgres** `.global()` writer from a row-client (postgres.js/pg over Hyperdrive). */
 declare const createPostgresGlobalCtxDb: (client: RowClient, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
 /** Convenience: a **MySQL** `.global()` writer from a `mysql2/promise` connection/pool (created with `flags: ["FOUND_ROWS"]`). */
-declare const createMysqlGlobalCtxDb: (connection: Mysql2Execute, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
-export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+declare const createMysqlGlobalCtxDb: (connection: Mysql2Client, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
+/** The studio's global data browser over a Hyperdrive database — every table in the connection's schema, internal ones hidden. */
+interface HyperdriveGlobalIntrospector {
+  facetColumn: (options: FacetGlobalColumnOptions) => Promise<GlobalFacetResult>;
+  listTables: () => Promise<GlobalTableInfo[]>;
+  readTablePage: (options: ReadGlobalTablePageOptions) => Promise<GlobalTablePage>;
+}
+/** Build the studio's global-browser introspector for a Hyperdrive `.global()` store. */
+declare const createHyperdriveGlobalIntrospector: (engine: HyperdriveEngine, exec: SqlExec, schema: SchemaLike) => HyperdriveGlobalIntrospector;
+/**
+ * The admin CDC sync's global plane on Hyperdrive: a page of the global
+ * `__cdc_log` past `sinceSeq`. The log only exists once a CDC-enabled writer has
+ * run, so its absence is "nothing has changed yet" — an empty page that leaves
+ * the cursor where it was — not an error.
+ */
+declare const readHyperdriveGlobalCdc: (engine: HyperdriveEngine, exec: SqlExec, request: {
+  limit?: number;
+  now?: number;
+  sinceSeq: number;
+}) => Promise<{
+  changes: CdcChange[];
+  cursor: number;
+}>;
+/**
+ * The admin point-in-time apply's global plane on Hyperdrive: replay CDC changes
+ * in order through the store core (insert, falling back to replace). The writer
+ * carries the app's `cdc` setting so the replay appends to the global changelog
+ * like any other write. Returns the number replayed.
+ */
+declare const applyHyperdriveGlobalCdc: (options: {
+  cdc: boolean;
+  changes: ReadonlyArray<CdcChange>;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+}) => Promise<number>;
+export { CreateHyperdriveGlobalCtxDbOptions, ExportHyperdriveGlobalRowsOptions, HyperdriveEngine, HyperdriveGlobalIntrospector, ImportHyperdriveGlobalRowsOptions, type Mysql2Client, type PgVectorIndexOptions, type RowClient, applyHyperdriveGlobalCdc, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createHyperdriveGlobalIntrospector, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, exportHyperdriveGlobalRows, importHyperdriveGlobalRows, mysqlDialect, postgresDialect, readHyperdriveGlobalCdc };

package/dist/global.mjs

@@ -1,9 +1 @@
-import { createSqlCtxDb } from '@lunora/sql-store';
-import { postgresDialect, mysqlDialect } from './packem_shared/mysqlDialect-oNhZ58s8.mjs';
-import { buildMysqlExec, buildPgExec } from './packem_shared/buildMysqlExec-DBbCjyq3.mjs';
-
-const createHyperdriveGlobalCtxDb = ({ engine, exec, ...rest }) => createSqlCtxDb({ ...rest, dialect: engine === "postgres" ? postgresDialect : mysqlDialect, exec });
-const createPostgresGlobalCtxDb = (client, options) => createHyperdriveGlobalCtxDb({ ...options, engine: "postgres", exec: buildPgExec(client) });
-const createMysqlGlobalCtxDb = (connection, options) => createHyperdriveGlobalCtxDb({ ...options, engine: "mysql", exec: buildMysqlExec(connection) });
-
-export { buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+import{applyCdcChanges as d,CDC_LOG_TABLE as b}from"@lunora/shard-engine";import{createSqlCtxDb as p,readSqlGlobalTablePage as g,listSqlGlobalTables as m,facetSqlGlobalColumn as y,exportSqlGlobalRows as C,importSqlGlobalRows as G,readSqlCdcChanges as x}from"@lunora/sql-store";import{postgresDialect as q,mysqlDialect as u}from"./packem_shared/mysqlDialect-BS1Sz60B.mjs";import{buildMysqlExec as f,buildPgExec as v}from"./packem_shared/buildMysqlExec-DrnJfCYF.mjs";import{createPgVectorIndex as A}from"./packem_shared/createPgVectorIndex-B2Wbzqns.mjs";const o=e=>e==="postgres"?q:u,c=({engine:e,exec:l,...r})=>p({...r,dialect:o(e),exec:l}),H=({engine:e,exec:l,schema:r,tables:t})=>C(l,r,o(e),t===void 0?{}:{tables:t}),P=({cdc:e,dryRun:l,engine:r,exec:t,onConflict:a,rows:s,schema:n,startLine:i})=>G(c({cdc:e,engine:r,exec:t,schema:n}),n,o(r),{dryRun:l===!0,exec:t,onConflict:a??"skip",rows:s,...i===void 0?{}:{startLine:i}}),R=(e,l)=>c({...l,engine:"postgres",exec:v(e)}),T=(e,l)=>c({...l,engine:"mysql",exec:f(e)}),E=(e,l,r)=>{const t=o(e);return{facetColumn:a=>y(l,r,t,a),listTables:()=>m(l,r,t),readTablePage:a=>g(l,r,t,a)}},I=async(e,l,r)=>{const t=o(e),{params:a,sql:s}=t.render(t.tableExists(b));return(await l.all(s,a)).length===0?{changes:[],cursor:r.sinceSeq}:x(l,r,t)},M=async e=>(await d(c({cdc:e.cdc,engine:e.engine,exec:e.exec,schema:e.schema}),e.changes),e.changes.length);export{M as applyHyperdriveGlobalCdc,f as buildMysqlExec,v as buildPgExec,c as createHyperdriveGlobalCtxDb,E as createHyperdriveGlobalIntrospector,T as createMysqlGlobalCtxDb,A as createPgVectorIndex,R as createPostgresGlobalCtxDb,H as exportHyperdriveGlobalRows,P as importHyperdriveGlobalRows,u as mysqlDialect,q as postgresDialect,I as readHyperdriveGlobalCdc};