@lunora/hyperdrive 1.0.0-alpha.8 → 1.0.0-alpha.81

package/dist/index.d.ts

@@ -1,165 +1,148 @@
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-DE1NYxyA.js";
 /**
-* Public types for `@lunora/hyperdrive`.
-*
-* Hyperdrive points at a database **Lunora does not own**. Everything here is
-* deliberately structural (no hard dependency on `@cloudflare/workers-types` or
-* any SQL driver) so unit tests can pass plain-object doubles, exactly like the
-* `D1DatabaseLike` projection in `@lunora/d1`.
-*
-* The hard constraint, restated wherever this surface is used: Hyperdrive
-* queries are **non-deterministic** (forbidden in `query`/`mutation`, allowed
-* only in `action`s — see the `hyperdrive_outside_action` advisor lint), and
-* external writes are **invisible to Lunora live queries** — a subscription will
-* NOT re-run when an external Postgres/MySQL row changes.
-*/
-/**
-* Structural projection of the Cloudflare `Hyperdrive` binding (`env.HYPERDRIVE`).
-*
-* Mirrors the fields of the real `Hyperdrive` from `@cloudflare/workers-types`
-* but stays structural so a unit test can pass a plain object. At runtime only
-* `connectionString` is needed to construct a driver; the discrete connection
-* parts are surfaced for drivers that prefer a config object over a DSN.
-*/
-interface HyperdriveLike {
-  /** A connection string Hyperdrive routes through its pooled, cached edge connection. */
+ * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
+ * user-supplied SQL driver.
+ *
+ * `@lunora/hyperdrive` deliberately **bundles no driver** — `postgres`, `pg` and
+ * `mysql2` are heavy and the choice is the user's (they are `optional`
+ * `peerDependencies`, never `dependencies`). This factory's only job is to lift
+ * the binding's connection details out; the user constructs their own driver
+ * from `connectionString` and wraps it with one of the {@link fromPostgresJs} /
+ * {@link fromNodePg} / {@link fromMysql2} adapters to get a {@link SqlClient}.
+ * @example
+ * ```ts
+ * import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
+ * import postgres from "postgres";
+ *
+ * // inside an action (never a query/mutation):
+ * const { connectionString } = createHyperdrive(env.HYPERDRIVE);
+ * ctx.sql = fromPostgresJs(postgres(connectionString));
+ * const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
+ * ```
+ * @remarks
+ * Hyperdrive talks to an **external** database Lunora has no visibility into.
+ * Queries through `ctx.sql` are non-deterministic (action-only — enforced by the
+ * `hyperdrive_outside_action` advisor lint) and external writes are NOT tracked
+ * by Lunora live queries: subscriptions will not re-run when external rows
+ * change. Use Hyperdrive to *integrate* an existing DB from an action; if you
+ * want that data to be reactive, write a projection of it into a `defineSchema`
+ * DO/D1 table.
+ * @param binding The `env.HYPERDRIVE` binding (or a structural double).
+ * @returns The raw `connectionString` plus the discrete connection parts.
+ */
+declare const createHyperdrive: (binding: HyperdriveLike) => {
+  config: HyperdriveConnection;
   connectionString: string;
-  /** Database name component of the connection. */
-  database: string;
-  /** Host Hyperdrive presents to the driver (the local proxy, not your origin DB). */
-  host: string;
-  /** Password component of the connection. */
-  password: string;
-  /** Port Hyperdrive presents to the driver. */
-  port: number;
-  /** User component of the connection. */
-  user: string;
-}
+};
 /**
-* The connection config surfaced by {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive}: the raw
-* `connectionString` plus the discrete parts, ready to hand to a driver.
-*/
-interface HyperdriveConnection {
-  /** Database name. */
-  database: string;
-  /** Host (Hyperdrive's local proxy). */
-  host: string;
-  /** Password. */
-  password: string;
-  /** Port. */
-  port: number;
-  /** User. */
-  user: string;
-}
+ * Wrap a `postgres` (postgres.js) client as a {@link SqlClient}.
+ *
+ * Uses the driver's `.unsafe(text, params)` escape hatch so the caller supplies
+ * a plain SQL string with `$1, $2, …` placeholders and a positional params
+ * array. postgres.js's `.unsafe` resolves to a row array.
+ */
+declare const fromPostgresJs: (client: PostgresJsLike) => SqlClient;
+/**
+ * Wrap a `pg` (node-postgres) `Client` or `Pool` as a {@link SqlClient}.
+ *
+ * node-postgres returns a result object whose `rows` field holds the row array.
+ */
+declare const fromNodePg: (client: NodePgLike) => SqlClient;
 /**
-* The driver-agnostic SQL surface bound to `ctx.sql` on **`ActionCtx` only**.
-*
-* This is the exact type the generated ctx imports as
-* `import("@lunora/hyperdrive").SqlClient`. Keep the name and shape stable — the
-* codegen ctx wiring (Phase 1) depends on it.
-*
-* It is intentionally minimal — a single parameterised `query` — so it maps onto
-* `postgres` (postgres.js), `pg` (node-postgres) and `mysql2` alike via the
-* {@link import("./create-hyperdrive").fromPostgresJs | fromPostgresJs} /
-* {@link import("./create-hyperdrive").fromNodePg | fromNodePg} /
-* {@link import("./create-hyperdrive").fromMysql2 | fromMysql2} adapters. Use
-* positional placeholders that match your driver (`$1, $2` for Postgres, `?` for
-* MySQL); the package does not rewrite SQL.
-*
-* Reminder (also on the emitted JSDoc): non-deterministic, action-only,
-* non-reactive — writes here are not tracked by Lunora live queries.
-*/
-interface SqlClient {
+ * Wrap a `mysql2/promise` connection or pool as a {@link SqlClient}.
+ *
+ * Use `?` placeholders (MySQL positional syntax). `mysql2`'s `execute` resolves
+ * to a `[rows, fields]` tuple; the adapter returns the first element. For a
+ * non-`SELECT` (DML), `mysql2` yields a `ResultSetHeader` object rather than a
+ * row array, so the adapter normalises that to `[]` — matching the empty-array
+ * contract the postgres.js / node-postgres adapters already honour.
+ */
+declare const fromMysql2: (connection: Mysql2Like) => SqlClient;
+/** How an external row maps to a Lunora document. */
+interface ProjectOptions {
+  /**
+   * Column whose value becomes the Lunora `_id` (stringified). Defaults to `"id"`.
+   * With no `map`, this column is dropped from the document body (it lives on as
+   * `_id`); with a `map`, the mapper owns the body and `_id` is added from here.
+   */
+  idColumn?: string;
   /**
-  * Run a parameterised SQL statement and return the result rows.
-  * @param text SQL text with driver-native positional placeholders.
-  * @param params Bound parameter values, positionally matched to `text`.
-  * @returns The rows the statement produced (empty for non-`SELECT`s that
-  * return no rows).
-  */
-  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
+   * Transform an external row into the stored document body. Omit for the default:
+   * every selected column except `idColumn` is copied verbatim. The returned object
+   * must not include `_id` — it is set from `idColumn`.
+   */
+  map?: (row: Record<string, unknown>) => Record<string, unknown>;
 }
-/**
-* Structural projection of a `pg` (node-postgres) `Client`/`Pool`. Only the
-* `query` method `fromNodePg` calls is required, kept structural for testing.
-*/
-interface NodePgLike {
-  query: (text: string, params?: ReadonlyArray<unknown>) => Promise<{
-    rows: unknown[];
-  }>;
+/** Options for {@link pullSourceRows}: the parameterised tenant query plus the row projection. */
+interface PullSourceOptions extends ProjectOptions {
+  /** Bound parameter values, positionally matched to `query` (the tenant scope binds here). */
+  params?: ReadonlyArray<unknown>;
+  /** The full tenant-membership query with driver-native placeholders (`$1` / `?`). */
+  query: string;
 }
 /**
-* Structural projection of a `postgres` (postgres.js) tagged-template client.
-* The adapter uses the `.unsafe(text, params)` escape hatch so callers keep
-* full control of the parameter list.
-*/
-interface PostgresJsLike {
-  unsafe: (text: string, params?: ReadonlyArray<unknown>) => Promise<unknown>;
-}
+ * Project one external row to a Lunora document: lift `idColumn` to a stringified
+ * `_id`, then either apply `map` or copy every other column verbatim. Throws when
+ * the id column is missing/nullish so a misconfigured query fails loudly rather than
+ * materializing rows under an `"undefined"` id.
+ *
+ * Delegates to `@lunora/shard-engine`'s `liftSourceId` — the single id-lift the declarative
+ * `.source()` poll loop also uses — so the manual bridge and the codegen path can
+ * never diverge in their missing-id handling.
+ */
+declare const projectSourceRow: (row: Record<string, unknown>, options?: ProjectOptions) => Record<string, unknown>;
 /**
-* Structural projection of a `mysql2/promise` connection/pool. `mysql2`'s
-* `execute` resolves to a `[rows, fields]` tuple; the adapter takes the first
-* element as the rows.
-*/
-interface Mysql2Like {
-  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
-}
+ * Run a parameterised tenant query against Hyperdrive and project every row to a
+ * Lunora document ready to hand to `materializeExternalRows`. Call this inside an
+ * **action** (where `ctx.sql` lives); pass the result to a mutation for the write.
+ */
+declare const pullSourceRows: (sql: SqlClient, options: PullSourceOptions) => Promise<Record<string, unknown>[]>;
+export { type HyperdriveConnection, type HyperdriveLike, type Mysql2Like, type NodePgLike, type PostgresJsLike, type ProjectOptions, type PullSourceOptions, type SqlClient,
 /**
-* Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
-* user-supplied SQL driver.
-*
-* `@lunora/hyperdrive` deliberately **bundles no driver** — `postgres`, `pg` and
-* `mysql2` are heavy and the choice is the user's (they are `optional`
-* `peerDependencies`, never `dependencies`). This factory's only job is to lift
-* the binding's connection details out; the user constructs their own driver
-* from `connectionString` and wraps it with one of the {@link fromPostgresJs} /
-* {@link fromNodePg} / {@link fromMysql2} adapters to get a {@link SqlClient}.
-* @example
-* ```ts
-* import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
-* import postgres from "postgres";
-*
-* // inside an action (never a query/mutation):
-* const { connectionString } = createHyperdrive(env.HYPERDRIVE);
-* ctx.sql = fromPostgresJs(postgres(connectionString));
-* const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
-* ```
-* @remarks
-* Hyperdrive talks to an **external** database Lunora has no visibility into.
-* Queries through `ctx.sql` are non-deterministic (action-only — enforced by the
-* `hyperdrive_outside_action` advisor lint) and external writes are NOT tracked
-* by Lunora live queries: subscriptions will not re-run when external rows
-* change. Use Hyperdrive to *integrate* an existing DB from an action; if you
-* want that data to be reactive, write a projection of it into a `defineSchema`
-* DO/D1 table.
-* @param binding The `env.HYPERDRIVE` binding (or a structural double).
-* @returns The raw `connectionString` plus the discrete connection parts.
-*/
-declare const createHyperdrive: (binding: HyperdriveLike) => {
-  config: HyperdriveConnection;
-  connectionString: string;
-};
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+createHyperdrive,
 /**
-* Wrap a `postgres` (postgres.js) client as a {@link SqlClient}.
-*
-* Uses the driver's `.unsafe(text, params)` escape hatch so the caller supplies
-* a plain SQL string with `$1, $2, …` placeholders and a positional params
-* array. postgres.js's `.unsafe` resolves to a row array.
-*/
-declare const fromPostgresJs: (client: PostgresJsLike) => SqlClient;
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+fromMysql2,
 /**
-* Wrap a `pg` (node-postgres) `Client` or `Pool` as a {@link SqlClient}.
-*
-* node-postgres returns a result object whose `rows` field holds the row array.
-*/
-declare const fromNodePg: (client: NodePgLike) => SqlClient;
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+fromNodePg,
 /**
-* Wrap a `mysql2/promise` connection or pool as a {@link SqlClient}.
-*
-* Use `?` placeholders (MySQL positional syntax). `mysql2`'s `execute` resolves
-* to a `[rows, fields]` tuple; the adapter returns the first element. For a
-* non-`SELECT` (DML), `mysql2` yields a `ResultSetHeader` object rather than a
-* row array, so the adapter normalises that to `[]` — matching the empty-array
-* contract the postgres.js / node-postgres adapters already honour.
-*/
-declare const fromMysql2: (connection: Mysql2Like) => SqlClient;
-export { type HyperdriveConnection, type HyperdriveLike, type Mysql2Like, type NodePgLike, type PostgresJsLike, type SqlClient, createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs };
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+fromPostgresJs, projectSourceRow, pullSourceRows };

package/dist/index.mjs

@@ -1 +1 @@
-export { createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs } from './packem_shared/createHyperdrive-DD8GoDZo.mjs';
+import{createHyperdrive as e,fromMysql2 as f,fromNodePg as m,fromPostgresJs as p}from"./packem_shared/createHyperdrive-DEXMfGd0.mjs";import{projectSourceRow as t,pullSourceRows as c}from"./packem_shared/projectSourceRow-DN8ywPRl.mjs";export{e as createHyperdrive,f as fromMysql2,m as fromNodePg,p as fromPostgresJs,t as projectSourceRow,c as pullSourceRows};

package/dist/packem_shared/buildMysqlExec-DriYb1l9.mjs

@@ -0,0 +1 @@
+const u=e=>({all:(r,a)=>e.query(r,a),batch:async r=>{await Promise.all(r.map(a=>e.query(a.sql,a.params)))},run:async(r,a)=>(await e.query(r,a),{rowsAffected:0})}),t=e=>({all:async(r,a)=>{const[s]=await e.execute(r,a);return s},batch:async r=>{await Promise.all(r.map(a=>e.execute(a.sql,a.params)))},run:async(r,a)=>{const[s]=await e.execute(r,a);return{rowsAffected:s.affectedRows??0}}});export{t as buildMysqlExec,u as buildPgExec};

package/dist/packem_shared/createHyperdrive-DEXMfGd0.mjs

@@ -0,0 +1 @@
+const o=r=>({config:{database:r.database,host:r.host,password:r.password,port:r.port,user:r.user},connectionString:r.connectionString}),a=r=>({query:async(t,s=[])=>await r.unsafe(t,s)}),c=r=>({query:async(t,s=[])=>(await r.query(t,s)).rows}),n=r=>({query:async(t,s=[])=>{const[e]=await r.execute(t,s);return Array.isArray(e)?e:[]}});export{o as createHyperdrive,n as fromMysql2,c as fromNodePg,a as fromPostgresJs};

package/dist/packem_shared/mysqlDialect-DitNAlpV.mjs

@@ -0,0 +1 @@
+import{sqliteEncode as E,sqliteDecode as m}from"@lunora/sql-store";import{sql as t}from"drizzle-orm";const i="__id__",a="__vector__",r=e=>t`${t.identifier(e)}.${t.identifier(a)}`,T=e=>t`to_tsvector('simple', ${e})`,o=e=>t`to_tsquery('simple', ${e.map((n,s)=>s===e.length-1?`${n}:*`:n).join(" & ")})`,l=/duplicate key value violates unique constraint/iu,c=e=>{switch(e){case"array":case"object":case"record":return"JSON";case"bigint":return"VARCHAR(64)";case"boolean":return"TINYINT";case"bytes":return"LONGBLOB";case"date":case"number":case"timestamp":return"DOUBLE";default:return"LONGTEXT"}},u=/TEXT|BLOB/u,_={companionTypes:{autoincrementPrimaryKey:"BIGSERIAL PRIMARY KEY",integer:"INTEGER",key:"TEXT",real:"DOUBLE PRECISION",text:"TEXT"},columnType:e=>{switch(e){case"boolean":return"INTEGER";case"bytes":return"BYTEA";case"date":case"number":case"timestamp":return"DOUBLE PRECISION";default:return"TEXT"}},decode:m,encode:E,frameworkColumns:()=>[{name:"id",type:"TEXT PRIMARY KEY"},{name:"_creationTime",type:"DOUBLE PRECISION NOT NULL"}],isUniqueViolation:e=>{const{code:n}=e;return n==="23505"||e instanceof Error&&l.test(e.message)},maxTableColumns:1600,name:"postgres",supportsFts5:!1,nativeTextSearch:{createCompanion:(e,n)=>t`CREATE TABLE IF NOT EXISTS ${t.identifier(e)} (${t.identifier(i)} ${t.raw(n)} PRIMARY KEY, ${t.identifier(a)} tsvector)`,createIndexes:e=>[t`CREATE INDEX IF NOT EXISTS ${t.identifier(`${e}__gin`)} ON ${t.identifier(e)} USING GIN (${t.identifier(a)})`],indexDocument:(e,n,s)=>t`INSERT INTO ${t.identifier(e)} (${t.identifier(i)}, ${t.identifier(a)}) VALUES (${n}, ${T(s)})`,matches:(e,n)=>t`${r(e)} @@ ${o(n)}`,rank:(e,n)=>t`ts_rank_cd(${r(e)}, ${o(n)})`},supportsReturning:!0,textPatternOperatorClass:"text_pattern_ops",tableExists:e=>t`SELECT table_name FROM information_schema.tables WHERE table_schema = ANY (current_schemas(false)) AND table_name = ${e}`},I={affectedRows:e=>e.rowsAffected,companionTypes:{autoincrementPrimaryKey:"BIGINT AUTO_INCREMENT PRIMARY KEY",integer:"INTEGER",key:"VARCHAR(768)",real:"DOUBLE",text:"LONGTEXT"},columnType:c,decode:m,encode:E,frameworkColumns:()=>[{name:"id",type:"VARCHAR(768) PRIMARY KEY"},{name:"_creationTime",type:"DOUBLE NOT NULL"}],indexKeyPrefix:e=>u.test(c(e))?191:void 0,isUniqueViolation:e=>{const n=e;return n.errno===1062||n.code==="ER_DUP_ENTRY"},maxTableColumns:4096,name:"mysql",supportsFts5:!1,supportsReturning:!1,tableExists:e=>t`SELECT table_name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ${e}`};export{I as mysqlDialect,_ as postgresDialect};

package/dist/packem_shared/projectSourceRow-DN8ywPRl.mjs

@@ -0,0 +1 @@
+import{liftSourceId as a}from"@lunora/shard-engine";const n=(o,r={})=>a(o,r),w=async(o,r)=>{const{idColumn:t,map:c,params:s,query:e}=r;return(await o.query(e,s)).map(u=>n(u,{idColumn:t,map:c}))};export{n as projectSourceRow,w as pullSourceRows};

package/dist/packem_shared/types.d-DE1NYxyA.d.mts

@@ -0,0 +1,113 @@
+/**
+ * Public types for `@lunora/hyperdrive`.
+ *
+ * Hyperdrive points at a database **Lunora does not own**. Everything here is
+ * deliberately structural (no hard dependency on `@cloudflare/workers-types` or
+ * any SQL driver) so unit tests can pass plain-object doubles, exactly like the
+ * `D1DatabaseLike` projection in `@lunora/d1`.
+ *
+ * The hard constraint, restated wherever this surface is used: Hyperdrive
+ * queries are **non-deterministic** (forbidden in `query`/`mutation`, allowed
+ * only in `action`s — see the `hyperdrive_outside_action` advisor lint), and
+ * external writes are **invisible to Lunora live queries** — a subscription will
+ * NOT re-run when an external Postgres/MySQL row changes.
+ */
+/**
+ * Structural projection of the Cloudflare `Hyperdrive` binding (`env.HYPERDRIVE`).
+ *
+ * Mirrors the fields of the real `Hyperdrive` from `@cloudflare/workers-types`
+ * but stays structural so a unit test can pass a plain object. At runtime only
+ * `connectionString` is needed to construct a driver; the discrete connection
+ * parts are surfaced for drivers that prefer a config object over a DSN.
+ */
+interface HyperdriveLike {
+  /** A connection string Hyperdrive routes through its pooled, cached edge connection. */
+  connectionString: string;
+  /** Database name component of the connection. */
+  database: string;
+  /** Host Hyperdrive presents to the driver (the local proxy, not your origin DB). */
+  host: string;
+  /** Password component of the connection. */
+  password: string;
+  /** Port Hyperdrive presents to the driver. */
+  port: number;
+  /** User component of the connection. */
+  user: string;
+}
+/**
+ * The connection config surfaced by {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive}: the raw
+ * `connectionString` plus the discrete parts, ready to hand to a driver.
+ */
+interface HyperdriveConnection {
+  /** Database name. */
+  database: string;
+  /** Host (Hyperdrive's local proxy). */
+  host: string;
+  /** Password. */
+  password: string;
+  /** Port. */
+  port: number;
+  /** User. */
+  user: string;
+}
+/**
+ * The driver-agnostic SQL surface bound to `ctx.sql` on **`ActionCtx` only**.
+ *
+ * This is the exact type the generated ctx imports as
+ * `import("@lunora/hyperdrive").SqlClient`. Keep the name and shape stable — the
+ * codegen ctx wiring (Phase 1) depends on it.
+ *
+ * It is intentionally minimal — a single parameterised `query` — so it maps onto
+ * `postgres` (postgres.js), `pg` (node-postgres) and `mysql2` alike via the
+ * {@link import("./create-hyperdrive").fromPostgresJs | fromPostgresJs} /
+ * {@link import("./create-hyperdrive").fromNodePg | fromNodePg} /
+ * {@link import("./create-hyperdrive").fromMysql2 | fromMysql2} adapters. Use
+ * positional placeholders that match your driver (`$1, $2` for Postgres, `?` for
+ * MySQL); the package does not rewrite SQL.
+ *
+ * Reminder (also on the emitted JSDoc): non-deterministic, action-only,
+ * non-reactive — writes here are not tracked by Lunora live queries.
+ */
+interface SqlClient {
+  /**
+   * Run a parameterised SQL statement and return the result rows.
+   *
+   * SECURITY: `text` is executed verbatim — the package never rewrites or
+   * escapes it. NEVER interpolate untrusted/user input into `text`; put every
+   * value in `params` and reference it with a positional placeholder (`$1`/`?`).
+   * Building `text` by string-concatenating request data is a SQL-injection
+   * sink against your own Postgres/MySQL. Identifiers (table/column names) can't
+   * be parameterised — allowlist them against a fixed set, don't interpolate.
+   * @param text SQL text with driver-native positional placeholders.
+   * @param params Bound parameter values, positionally matched to `text`.
+   * @returns The rows the statement produced (empty for non-`SELECT`s that
+   * return no rows).
+   */
+  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
+}
+/**
+ * Structural projection of a `pg` (node-postgres) `Client`/`Pool`. Only the
+ * `query` method `fromNodePg` calls is required, kept structural for testing.
+ */
+interface NodePgLike {
+  query: (text: string, params?: ReadonlyArray<unknown>) => Promise<{
+    rows: unknown[];
+  }>;
+}
+/**
+ * Structural projection of a `postgres` (postgres.js) tagged-template client.
+ * The adapter uses the `.unsafe(text, params)` escape hatch so callers keep
+ * full control of the parameter list.
+ */
+interface PostgresJsLike {
+  unsafe: (text: string, params?: ReadonlyArray<unknown>) => Promise<unknown>;
+}
+/**
+ * Structural projection of a `mysql2/promise` connection/pool. `mysql2`'s
+ * `execute` resolves to a `[rows, fields]` tuple; the adapter takes the first
+ * element as the rows.
+ */
+interface Mysql2Like {
+  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
+}
+export { HyperdriveLike as H, Mysql2Like as M, NodePgLike as N, PostgresJsLike as P, SqlClient as S, HyperdriveConnection as a };

package/dist/packem_shared/types.d-DE1NYxyA.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Public types for `@lunora/hyperdrive`.
+ *
+ * Hyperdrive points at a database **Lunora does not own**. Everything here is
+ * deliberately structural (no hard dependency on `@cloudflare/workers-types` or
+ * any SQL driver) so unit tests can pass plain-object doubles, exactly like the
+ * `D1DatabaseLike` projection in `@lunora/d1`.
+ *
+ * The hard constraint, restated wherever this surface is used: Hyperdrive
+ * queries are **non-deterministic** (forbidden in `query`/`mutation`, allowed
+ * only in `action`s — see the `hyperdrive_outside_action` advisor lint), and
+ * external writes are **invisible to Lunora live queries** — a subscription will
+ * NOT re-run when an external Postgres/MySQL row changes.
+ */
+/**
+ * Structural projection of the Cloudflare `Hyperdrive` binding (`env.HYPERDRIVE`).
+ *
+ * Mirrors the fields of the real `Hyperdrive` from `@cloudflare/workers-types`
+ * but stays structural so a unit test can pass a plain object. At runtime only
+ * `connectionString` is needed to construct a driver; the discrete connection
+ * parts are surfaced for drivers that prefer a config object over a DSN.
+ */
+interface HyperdriveLike {
+  /** A connection string Hyperdrive routes through its pooled, cached edge connection. */
+  connectionString: string;
+  /** Database name component of the connection. */
+  database: string;
+  /** Host Hyperdrive presents to the driver (the local proxy, not your origin DB). */
+  host: string;
+  /** Password component of the connection. */
+  password: string;
+  /** Port Hyperdrive presents to the driver. */
+  port: number;
+  /** User component of the connection. */
+  user: string;
+}
+/**
+ * The connection config surfaced by {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive}: the raw
+ * `connectionString` plus the discrete parts, ready to hand to a driver.
+ */
+interface HyperdriveConnection {
+  /** Database name. */
+  database: string;
+  /** Host (Hyperdrive's local proxy). */
+  host: string;
+  /** Password. */
+  password: string;
+  /** Port. */
+  port: number;
+  /** User. */
+  user: string;
+}
+/**
+ * The driver-agnostic SQL surface bound to `ctx.sql` on **`ActionCtx` only**.
+ *
+ * This is the exact type the generated ctx imports as
+ * `import("@lunora/hyperdrive").SqlClient`. Keep the name and shape stable — the
+ * codegen ctx wiring (Phase 1) depends on it.
+ *
+ * It is intentionally minimal — a single parameterised `query` — so it maps onto
+ * `postgres` (postgres.js), `pg` (node-postgres) and `mysql2` alike via the
+ * {@link import("./create-hyperdrive").fromPostgresJs | fromPostgresJs} /
+ * {@link import("./create-hyperdrive").fromNodePg | fromNodePg} /
+ * {@link import("./create-hyperdrive").fromMysql2 | fromMysql2} adapters. Use
+ * positional placeholders that match your driver (`$1, $2` for Postgres, `?` for
+ * MySQL); the package does not rewrite SQL.
+ *
+ * Reminder (also on the emitted JSDoc): non-deterministic, action-only,
+ * non-reactive — writes here are not tracked by Lunora live queries.
+ */
+interface SqlClient {
+  /**
+   * Run a parameterised SQL statement and return the result rows.
+   *
+   * SECURITY: `text` is executed verbatim — the package never rewrites or
+   * escapes it. NEVER interpolate untrusted/user input into `text`; put every
+   * value in `params` and reference it with a positional placeholder (`$1`/`?`).
+   * Building `text` by string-concatenating request data is a SQL-injection
+   * sink against your own Postgres/MySQL. Identifiers (table/column names) can't
+   * be parameterised — allowlist them against a fixed set, don't interpolate.
+   * @param text SQL text with driver-native positional placeholders.
+   * @param params Bound parameter values, positionally matched to `text`.
+   * @returns The rows the statement produced (empty for non-`SELECT`s that
+   * return no rows).
+   */
+  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
+}
+/**
+ * Structural projection of a `pg` (node-postgres) `Client`/`Pool`. Only the
+ * `query` method `fromNodePg` calls is required, kept structural for testing.
+ */
+interface NodePgLike {
+  query: (text: string, params?: ReadonlyArray<unknown>) => Promise<{
+    rows: unknown[];
+  }>;
+}
+/**
+ * Structural projection of a `postgres` (postgres.js) tagged-template client.
+ * The adapter uses the `.unsafe(text, params)` escape hatch so callers keep
+ * full control of the parameter list.
+ */
+interface PostgresJsLike {
+  unsafe: (text: string, params?: ReadonlyArray<unknown>) => Promise<unknown>;
+}
+/**
+ * Structural projection of a `mysql2/promise` connection/pool. `mysql2`'s
+ * `execute` resolves to a `[rows, fields]` tuple; the adapter takes the first
+ * element as the rows.
+ */
+interface Mysql2Like {
+  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
+}
+export { HyperdriveLike as H, Mysql2Like as M, NodePgLike as N, PostgresJsLike as P, SqlClient as S, HyperdriveConnection as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/hyperdrive",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-alpha.81",
   "description": "Bring-your-own Postgres/MySQL for Lunora via Cloudflare Hyperdrive: a driver-agnostic, action-only ctx.sql",
   "keywords": [
     "cloudflare",
@@ -50,8 +50,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/do": "1.0.0-alpha.8",
-    "@lunora/sql-store": "1.0.0-alpha.8",
+    "@lunora/shard-engine": "1.0.0-alpha.29",
+    "@lunora/sql-store": "1.0.0-alpha.81",
     "drizzle-orm": "^0.45.2"
   },
   "peerDependencies": {

package/dist/packem_shared/buildMysqlExec-DBbCjyq3.mjs

@@ -1,23 +0,0 @@
-const buildPgExec = (client) => {
-  return {
-    all: (sql, params) => client.query(sql, params),
-    run: async (sql, params) => {
-      await client.query(sql, params);
-      return { rowsAffected: 0 };
-    }
-  };
-};
-const buildMysqlExec = (connection) => {
-  return {
-    all: async (sql, params) => {
-      const [rows] = await connection.execute(sql, params);
-      return rows;
-    },
-    run: async (sql, params) => {
-      const [result] = await connection.execute(sql, params);
-      return { rowsAffected: result.affectedRows ?? 0 };
-    }
-  };
-};
-
-export { buildMysqlExec, buildPgExec };