@lunora/hyperdrive 1.0.0-alpha.115 → 1.0.0-alpha.117

package/README.md

@@ -42,7 +42,7 @@ Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-sa
 >
 > Hyperdrive talks to a database **Lunora does not own**. That breaks two invariants the rest of Lunora relies on:
 >
-> 1. **Non-deterministic (action-only).** A SQL query over Hyperdrive is a network call with an external, mutable result — exactly like `fetch`. It is **forbidden in `query`/`mutation`** (which must be deterministic so the coordinator can re-run them on OCC retry / subscription re-evaluation) and allowed **only in `action`s**. The `hyperdrive_outside_action` advisor lint flags `ctx.sql` used in a query/mutation.
+> 1. **Non-deterministic (action-only).** A SQL query over Hyperdrive is a network call with an external, mutable result — exactly like `fetch`. It is **forbidden in `query`/`mutation`** (which must be deterministic so the coordinator can re-run them on subscription re-evaluation; an OCC conflict surfaces as a `409` to the caller, not an internal retry) and allowed **only in `action`s**. The `hyperdrive_outside_action` advisor lint flags `ctx.sql` used in a query/mutation.
 > 2. **Non-reactive.** External writes do **not** flow through the Durable-Object / SQLite change-feed, so **Lunora live queries and subscriptions will NOT re-run** when an external Postgres/MySQL row changes. There is no honest way to make external writes reactive here.
 >
 > Use Hyperdrive to _read/write your existing DB from an action_. It is the **wrong** tool for "make my Postgres reactive". If you want external data to be reactive, write a **projection** of it into a `defineSchema` DO/D1 table from the action — that write _is_ tracked.

package/dist/global.d.mts

@@ -1,6 +1,6 @@
 import { DatabaseWriterLike } from '@lunora/shard-engine';
 import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
-import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-DE1NYxyA.mjs";
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-IgdRydpF.mjs";
 import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
 /**
  * Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg`

package/dist/global.d.ts

@@ -1,6 +1,6 @@
 import { DatabaseWriterLike } from '@lunora/shard-engine';
 import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
-import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-DE1NYxyA.js";
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-IgdRydpF.js";
 import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
 /**
  * Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg`

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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.mjs";
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-IgdRydpF.mjs";
 /**
  * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
  * user-supplied SQL driver.
@@ -14,9 +14,14 @@ import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as S
  * 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));
+ * // Wire the client once, on the app builder — called per shard construction,
+ * // not per request. `ctx.sql` is emitted `readonly`; it is never assigned.
+ * const app = defineApp<Env>()
+ *     .shard((env) => env.SHARD)
+ *     .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE).connectionString)))
+ *     .build();
+ *
+ * // Then, inside an action (never a query/mutation):
  * const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
  * ```
  * @remarks

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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";
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-IgdRydpF.js";
 /**
  * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
  * user-supplied SQL driver.
@@ -14,9 +14,14 @@ import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as S
  * 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));
+ * // Wire the client once, on the app builder — called per shard construction,
+ * // not per request. `ctx.sql` is emitted `readonly`; it is never assigned.
+ * const app = defineApp<Env>()
+ *     .shard((env) => env.SHARD)
+ *     .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE).connectionString)))
+ *     .build();
+ *
+ * // Then, inside an action (never a query/mutation):
  * const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
  * ```
  * @remarks

package/dist/packem_shared/{types.d-DE1NYxyA.d.mts → types.d-IgdRydpF.d.mts}

@@ -88,9 +88,11 @@ interface SqlClient {
 /**
  * Structural projection of a `pg` (node-postgres) `Client`/`Pool`. Only the
  * `query` method `fromNodePg` calls is required, kept structural for testing.
+ *
+ * Method syntax, not an arrow property — see {@link PostgresJsLike}.
  */
 interface NodePgLike {
-  query: (text: string, params?: ReadonlyArray<unknown>) => Promise<{
+  query(this: void, text: string, params?: ReadonlyArray<unknown>): Promise<{
     rows: unknown[];
   }>;
 }
@@ -98,16 +100,38 @@ interface NodePgLike {
  * 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.
+ *
+ * **`unsafe` is declared with METHOD syntax, and that is load-bearing.** Under
+ * `strictFunctionTypes` an arrow PROPERTY is checked contravariantly in its
+ * parameters, so a driver whose `unsafe` takes a MUTABLE array — which real
+ * postgres.js does (`parameters?: ParameterOrJSON<never>[]`) — is not assignable
+ * to one declared `params?: ReadonlyArray<unknown>`. As an arrow property this
+ * projection could therefore never accept the package it projects: every
+ * consumer got
+ * `TS2345: Argument of type 'Sql<{}>' is not assignable to parameter of type
+ * 'PostgresJsLike'`, and this repo's own test reached for
+ * `as unknown as PostgresJsLike` to get past it. Method syntax is checked
+ * bivariantly, which is what a structural projection of someone else's type
+ * needs — `readonly unknown[]` and postgres.js's mutable array relate in one
+ * direction, which is all bivariance asks for.
  */
 interface PostgresJsLike {
-  unsafe: (text: string, params?: ReadonlyArray<unknown>) => Promise<unknown>;
+  unsafe(this: void, 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.
+ *
+ * Method syntax, not an arrow property — see {@link PostgresJsLike} — but here
+ * that is necessary and NOT sufficient, so the live-driver test still casts.
+ * mysql2 types its second argument as a single `ExecuteValues`, a union of
+ * scalars, `ExecuteValues[]` and `{ [key: string]: ExecuteValues }`. Neither
+ * direction relates to `ReadonlyArray<unknown>`, so no variance rule can bridge
+ * it: closing this needs a deliberate widening of the parameter type here (and
+ * of what {@link SqlClient} promises), not a declaration-style change.
  */
 interface Mysql2Like {
-  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
+  execute(this: void, 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 → types.d-IgdRydpF.d.ts}

@@ -88,9 +88,11 @@ interface SqlClient {
 /**
  * Structural projection of a `pg` (node-postgres) `Client`/`Pool`. Only the
  * `query` method `fromNodePg` calls is required, kept structural for testing.
+ *
+ * Method syntax, not an arrow property — see {@link PostgresJsLike}.
  */
 interface NodePgLike {
-  query: (text: string, params?: ReadonlyArray<unknown>) => Promise<{
+  query(this: void, text: string, params?: ReadonlyArray<unknown>): Promise<{
     rows: unknown[];
   }>;
 }
@@ -98,16 +100,38 @@ interface NodePgLike {
  * 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.
+ *
+ * **`unsafe` is declared with METHOD syntax, and that is load-bearing.** Under
+ * `strictFunctionTypes` an arrow PROPERTY is checked contravariantly in its
+ * parameters, so a driver whose `unsafe` takes a MUTABLE array — which real
+ * postgres.js does (`parameters?: ParameterOrJSON<never>[]`) — is not assignable
+ * to one declared `params?: ReadonlyArray<unknown>`. As an arrow property this
+ * projection could therefore never accept the package it projects: every
+ * consumer got
+ * `TS2345: Argument of type 'Sql<{}>' is not assignable to parameter of type
+ * 'PostgresJsLike'`, and this repo's own test reached for
+ * `as unknown as PostgresJsLike` to get past it. Method syntax is checked
+ * bivariantly, which is what a structural projection of someone else's type
+ * needs — `readonly unknown[]` and postgres.js's mutable array relate in one
+ * direction, which is all bivariance asks for.
  */
 interface PostgresJsLike {
-  unsafe: (text: string, params?: ReadonlyArray<unknown>) => Promise<unknown>;
+  unsafe(this: void, 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.
+ *
+ * Method syntax, not an arrow property — see {@link PostgresJsLike} — but here
+ * that is necessary and NOT sufficient, so the live-driver test still casts.
+ * mysql2 types its second argument as a single `ExecuteValues`, a union of
+ * scalars, `ExecuteValues[]` and `{ [key: string]: ExecuteValues }`. Neither
+ * direction relates to `ReadonlyArray<unknown>`, so no variance rule can bridge
+ * it: closing this needs a deliberate widening of the parameter type here (and
+ * of what {@link SqlClient} promises), not a declaration-style change.
  */
 interface Mysql2Like {
-  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
+  execute(this: void, 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.115",
+  "version": "1.0.0-alpha.117",
   "description": "Bring-your-own Postgres/MySQL for Lunora via Cloudflare Hyperdrive: a driver-agnostic, action-only ctx.sql",
   "keywords": [
     "cloudflare",
@@ -51,9 +51,9 @@
   },
   "dependencies": {
     "@lunora/errors": "1.0.0-alpha.36",
-    "@lunora/platform": "1.0.0-alpha.30",
-    "@lunora/shard-engine": "1.0.0-alpha.64",
-    "@lunora/sql-store": "1.0.0-alpha.116",
+    "@lunora/platform": "1.0.0-alpha.32",
+    "@lunora/shard-engine": "1.0.0-alpha.69",
+    "@lunora/sql-store": "1.0.0-alpha.120",
     "drizzle-orm": "^0.45.2"
   },
   "peerDependencies": {