@lunora/hyperdrive 1.0.0-alpha.9 → 1.0.0-alpha.91

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/dist/global.d.mts

@@ -1,46 +1,105 @@
-import { DatabaseWriterLike } from '@lunora/do';
+import { DatabaseWriterLike } from '@lunora/shard-engine';
 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]>;
-}
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-DE1NYxyA.mjs";
+/**
+ * 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 — `execute` 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.
+ *
+ * Both fields are optional so a minimal `Mysql2Like` test double (only
+ * `execute`) safely resolves to "undeterminable" instead of a `TypeError`.
+ */
+type Mysql2Execute = Mysql2Like & {
+  config?: {
+    clientFlags?: number;
+  };
+  pool?: {
+    config?: {
+      connectionConfig?: {
+        clientFlags?: number;
+      };
+    };
+  };
+};
 /**
-* 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.
-*/
+ * 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).
+ */
 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.
-*/
+ * 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. Verified
+ * once here at construction — see {@link assertFoundRows} — never per statement.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`), same
+ * rationale as {@link buildPgExec}'s `batch` — `Mysql2Like` only exposes a
+ * single-statement `execute`, 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: 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`).
-*/
+ * **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;
 /** Which engine a Hyperdrive-backed `.global()` store targets. */
 type HyperdriveEngine = "mysql" | "postgres";
@@ -52,16 +111,12 @@ 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;
 /** 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"]`). */

package/dist/global.d.ts

@@ -1,46 +1,105 @@
-import { DatabaseWriterLike } from '@lunora/do';
+import { DatabaseWriterLike } from '@lunora/shard-engine';
 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]>;
-}
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-DE1NYxyA.js";
+/**
+ * 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 — `execute` 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.
+ *
+ * Both fields are optional so a minimal `Mysql2Like` test double (only
+ * `execute`) safely resolves to "undeterminable" instead of a `TypeError`.
+ */
+type Mysql2Execute = Mysql2Like & {
+  config?: {
+    clientFlags?: number;
+  };
+  pool?: {
+    config?: {
+      connectionConfig?: {
+        clientFlags?: number;
+      };
+    };
+  };
+};
 /**
-* 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.
-*/
+ * 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).
+ */
 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.
-*/
+ * 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. Verified
+ * once here at construction — see {@link assertFoundRows} — never per statement.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`), same
+ * rationale as {@link buildPgExec}'s `batch` — `Mysql2Like` only exposes a
+ * single-statement `execute`, 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: 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`).
-*/
+ * **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;
 /** Which engine a Hyperdrive-backed `.global()` store targets. */
 type HyperdriveEngine = "mysql" | "postgres";
@@ -52,16 +111,12 @@ 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;
 /** 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"]`). */

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{createSqlCtxDb as l}from"@lunora/sql-store";import{postgresDialect as s,mysqlDialect as c}from"./packem_shared/mysqlDialect-DitNAlpV.mjs";import{buildMysqlExec as i,buildPgExec as a}from"./packem_shared/buildMysqlExec-CPwtojyL.mjs";const o=({engine:e,exec:t,...r})=>l({...r,dialect:e==="postgres"?s:c,exec:t}),p=(e,t)=>o({...t,engine:"postgres",exec:a(e)}),g=(e,t)=>o({...t,engine:"mysql",exec:i(e)});export{i as buildMysqlExec,a as buildPgExec,o as createHyperdriveGlobalCtxDb,g as createMysqlGlobalCtxDb,p as createPostgresGlobalCtxDb,c as mysqlDialect,s as postgresDialect};