@lunora/hyperdrive 0.0.0 → 1.0.0-alpha.1

package/dist/global.d.mts

@@ -0,0 +1,69 @@
+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.
+*/
+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;
+/**
+* **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.)
+*/
+declare const mysqlDialect: SqlDialect;
+/** 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`. */
+interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dialect" | "exec"> {
+  /** The engine, selecting the Postgres or MySQL dialect. */
+  engine: HyperdriveEngine;
+  /** A Hyperdrive-backed exec, e.g. from {@link buildPgExec}/{@link buildMysqlExec}. */
+  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;
+/** 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 };

package/dist/global.d.ts

@@ -0,0 +1,69 @@
+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.
+*/
+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;
+/**
+* **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.)
+*/
+declare const mysqlDialect: SqlDialect;
+/** 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`. */
+interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dialect" | "exec"> {
+  /** The engine, selecting the Postgres or MySQL dialect. */
+  engine: HyperdriveEngine;
+  /** A Hyperdrive-backed exec, e.g. from {@link buildPgExec}/{@link buildMysqlExec}. */
+  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;
+/** 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 };

package/dist/global.mjs

@@ -0,0 +1,9 @@
+import { createSqlCtxDb } from '@lunora/sql-store';
+import { postgresDialect, mysqlDialect } from './packem_shared/postgresDialect-oNhZ58s8.mjs';
+import { buildMysqlExec, buildPgExec } from './packem_shared/buildPgExec-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 };

package/dist/index.d.mts

@@ -0,0 +1,165 @@
+/**
+* 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.
+  * @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]>;
+}
+/**
+* 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;
+};
+/**
+* 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;
+/**
+* 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 };

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+/**
+* 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.
+  * @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]>;
+}
+/**
+* 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;
+};
+/**
+* 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;
+/**
+* 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 };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs } from './packem_shared/createHyperdrive-DD8GoDZo.mjs';

package/dist/packem_shared/buildPgExec-DBbCjyq3.mjs

@@ -0,0 +1,23 @@
+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 };

package/dist/packem_shared/createHyperdrive-DD8GoDZo.mjs

@@ -0,0 +1,36 @@
+const createHyperdrive = (binding) => {
+  const config = {
+    database: binding.database,
+    host: binding.host,
+    password: binding.password,
+    port: binding.port,
+    user: binding.user
+  };
+  return { config, connectionString: binding.connectionString };
+};
+const fromPostgresJs = (client) => {
+  return {
+    query: async (text, params = []) => {
+      const rows = await client.unsafe(text, params);
+      return rows;
+    }
+  };
+};
+const fromNodePg = (client) => {
+  return {
+    query: async (text, params = []) => {
+      const result = await client.query(text, params);
+      return result.rows;
+    }
+  };
+};
+const fromMysql2 = (connection) => {
+  return {
+    query: async (text, params = []) => {
+      const [rows] = await connection.execute(text, params);
+      return Array.isArray(rows) ? rows : [];
+    }
+  };
+};
+
+export { createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs };

package/dist/packem_shared/postgresDialect-oNhZ58s8.mjs

@@ -0,0 +1,102 @@
+import { sqliteEncode, sqliteDecode } from '@lunora/sql-store';
+import { sql } from 'drizzle-orm';
+
+const PG_UNIQUE_VIOLATION_RE = /duplicate key value violates unique constraint/iu;
+const mysqlColumnType = (kind) => {
+  switch (kind) {
+    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";
+    }
+  }
+};
+const MYSQL_PREFIX_INDEX_RE = /TEXT|BLOB/u;
+const postgresDialect = {
+  companionTypes: {
+    autoincrementPrimaryKey: "BIGSERIAL PRIMARY KEY",
+    integer: "INTEGER",
+    key: "TEXT",
+    real: "DOUBLE PRECISION",
+    text: "TEXT"
+  },
+  columnType: (kind) => {
+    switch (kind) {
+      case "boolean": {
+        return "INTEGER";
+      }
+      case "bytes": {
+        return "BYTEA";
+      }
+      case "date":
+      case "number":
+      case "timestamp": {
+        return "DOUBLE PRECISION";
+      }
+      default: {
+        return "TEXT";
+      }
+    }
+  },
+  decode: (value, kind) => sqliteDecode(value, kind),
+  encode: (value) => sqliteEncode(value),
+  frameworkColumns: () => [
+    { name: "id", type: "TEXT PRIMARY KEY" },
+    { name: "_creationTime", type: "DOUBLE PRECISION NOT NULL" }
+  ],
+  isUniqueViolation: (error) => {
+    const { code } = error;
+    return code === "23505" || error instanceof Error && PG_UNIQUE_VIOLATION_RE.test(error.message);
+  },
+  name: "postgres",
+  supportsReturning: true,
+  tableExists: (table) => sql`SELECT table_name FROM information_schema.tables WHERE table_name = ${table}`
+};
+const mysqlDialect = {
+  affectedRows: (result) => result.rowsAffected,
+  companionTypes: {
+    autoincrementPrimaryKey: "BIGINT AUTO_INCREMENT PRIMARY KEY",
+    integer: "INTEGER",
+    // VARCHAR so it can be a PRIMARY KEY and be fully indexed (TEXT cannot,
+    // without a prefix length). 768 = InnoDB utf8mb4 single-column index limit.
+    key: "VARCHAR(768)",
+    real: "DOUBLE",
+    // Unbounded post-image storage (CDC `doc`); never an index key, so no bound.
+    text: "LONGTEXT"
+  },
+  columnType: (kind) => mysqlColumnType(kind),
+  decode: (value, kind) => sqliteDecode(value, kind),
+  encode: (value) => sqliteEncode(value),
+  frameworkColumns: () => [
+    { name: "id", type: "VARCHAR(768) PRIMARY KEY" },
+    { name: "_creationTime", type: "DOUBLE NOT NULL" }
+  ],
+  // InnoDB can't index a TEXT/LONGTEXT/BLOB column without a key prefix; bound it to 768 chars.
+  indexKeyPrefix: (kind) => MYSQL_PREFIX_INDEX_RE.test(mysqlColumnType(kind)) ? 768 : void 0,
+  isUniqueViolation: (error) => {
+    const candidate = error;
+    return candidate.errno === 1062 || candidate.code === "ER_DUP_ENTRY";
+  },
+  name: "mysql",
+  supportsReturning: false,
+  tableExists: (table) => sql`SELECT table_name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ${table}`
+};
+
+export { mysqlDialect, postgresDialect };