@onreza/sqlx-js 0.9.0 → 0.9.2

package/README.md

@@ -512,7 +512,7 @@ Regular `prepare` describes queries across a small connection pool (default 8, o
 | `--json`              | Machine-readable prepare diagnostics, doctor output, migration inspection and dry-runs. |
 | `--embed <path>`      | For `queries`: write a deterministic TypeScript map of referenced external SQL files. |
 | `--jsonl`             | Versioned streaming events for `prepare --watch`.                                     |
-| `--strict-inference`  | Fail prepare/dev/verify when nullability degrades or a generated query type contains `unknown`. |
+| `--strict-inference`  | Fail prepare/dev/verify when nullability degrades or a generated query type contains unresolved `unknown`. Intentional `JsonParameter<unknown>` wrappers remain accepted. |
 | `--force`             | For `migrate archive restore`: allow overwriting existing migration files.           |
 | `--lock-timeout <ms>` | Advisory-lock acquisition timeout for `migrate run` / `revert` / `dev` / `verify` / `squash`. |
 | `--shadow-url <url>`  | Use an existing disposable shadow DB instead of auto-creating one.                   |
@@ -714,7 +714,7 @@ declare global {
 export {};
 ```
 
-After re-running `prepare`, every `jsonb` column or parameter declared in `jsonbTypes` is checked against the corresponding TypeScript type. Columns without a custom mapping use `JsonValue` for result rows and `JsonParameter<unknown>` for parameters: the existential parameter type accepts any wrapper already proven JSON-safe by `sql.json(value)` without requiring domain interfaces to declare a string index signature. Non-JSON inputs such as `Date`, functions, and `bigint` are rejected by TypeScript while plain JSON objects, arrays, strings, numbers, booleans, and nested JSON `null` values are accepted. A bare top-level `null` remains SQL `NULL` and is allowed only when the mapped database parameter is nullable; use `sql.json(null)` for JSON `null`.
+After re-running `prepare`, every `jsonb` column or parameter declared in `jsonbTypes` is checked against the corresponding TypeScript type. Columns without a custom mapping use `JsonValue` for result rows and `JsonParameter<unknown>` for parameters: the existential parameter type accepts any wrapper already proven JSON-safe by `sql.json(value)` without requiring domain interfaces to declare a string index signature. `--strict-inference` accepts this intentional wrapper while continuing to reject unresolved `unknown` elsewhere in generated query contracts. Non-JSON inputs such as `Date`, functions, and `bigint` are rejected by TypeScript while plain JSON objects, arrays, strings, numbers, booleans, and nested JSON `null` values are accepted. A bare top-level `null` remains SQL `NULL` and is allowed only when the mapped database parameter is nullable; use `sql.json(null)` for JSON `null`.
 
 ### Direct scalar `columnTypes`
 

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import * as rt from "./postgres-runtime.js";
-import type { Typed as TypedFor, TypedFile as TypedFileFor, TypedSql as TypedSqlFor } from "./typed.js";
+import type { TypedFile as TypedFileFor, TypedForRegistry, TypedSqlForRegistry } from "./typed.js";
 import type { QueryParamsFor, QueryResultFor, QueryRowFor } from "./query.js";
 export interface KnownQueries {
 }
@@ -28,8 +28,8 @@ export type { TransactionOptions, MigrateOptions, OnQueryEvent, OnQueryHook, OnQ
 export type { ExecuteResult, JsonParameter, PgArrayParameter, JsonCompatible, KnownSqlState } from "./runtime.js";
 export type { PostgresClient, PostgresOptions, CreateClientOptions } from "./postgres-runtime.js";
 export type TypedFile = TypedFileFor<KnownFileQueries>;
-export type TypedSql = TypedSqlFor<KnownQueries, KnownFileQueries>;
-export type Typed = TypedFor<KnownQueries, KnownFileQueries, import("./runtime.js").TransactionOptions>;
+export type TypedSql = TypedSqlForRegistry<DefaultQueryRegistry>;
+export type Typed = TypedForRegistry<DefaultQueryRegistry, import("./runtime.js").TransactionOptions>;
 export type QueryRegistry = {
     queries: object;
     fileQueries: object;
@@ -40,12 +40,12 @@ export interface DefaultQueryRegistry {
     functions: KnownFunctions;
 }
 export type SqlClient<Registry extends QueryRegistry = DefaultQueryRegistry> = {
-    sql: TypedFor<Registry["queries"], Registry["fileQueries"], import("./runtime.js").TransactionOptions>;
+    sql: TypedForRegistry<Registry, import("./runtime.js").TransactionOptions>;
     unsafe: Unsafe;
     client: import("./postgres-runtime.js").PostgresClient;
     close: () => Promise<void>;
 };
-export type SqlExecutor<Registry extends QueryRegistry = DefaultQueryRegistry> = TypedSqlFor<Registry["queries"], Registry["fileQueries"]>;
+export type SqlExecutor<Registry extends QueryRegistry = DefaultQueryRegistry> = TypedSqlForRegistry<Registry>;
 export type QueryParams<Definition, Registry extends QueryRegistry = DefaultQueryRegistry> = QueryParamsFor<Definition, Registry>;
 export type QueryRow<Definition, Registry extends QueryRegistry = DefaultQueryRegistry> = QueryRowFor<Definition, Registry>;
 export type QueryResult<Definition, Registry extends QueryRegistry = DefaultQueryRegistry> = QueryResultFor<Definition, Registry>;

package/dist/src/query.d.ts

@@ -1,5 +1,5 @@
 import type { ExecuteResult } from "./runtime.js";
-import type { TypedSql } from "./typed.js";
+import type { TypedSqlForRegistry } from "./typed.js";
 export type QueryExecutionMode = "many" | "one" | "optional" | "execute";
 export type QueryExecutionMetadata = {
     queryId: string;
@@ -7,37 +7,46 @@ export type QueryExecutionMetadata = {
 };
 export declare const QUERY_EXECUTOR: unique symbol;
 export type QueryExecutorMethod = (mode: QueryExecutionMode, query: string, params: unknown[], metadata: QueryExecutionMetadata) => Promise<unknown>;
-type QueryEntry = {
-    params: unknown;
+type NamedQueryEntry = {
+    params: Record<string, unknown>;
+    row: unknown;
+};
+type PositionalQueryEntry = {
+    params: readonly unknown[];
     row: unknown;
 };
-type ParamsOf<T> = T extends {
-    params: infer P;
-} ? P extends readonly unknown[] ? P : [P] : never[];
-type RowOf<T> = T extends {
-    row: infer R;
-} ? R : never;
 type QueryModeResult<Mode extends QueryExecutionMode, Row> = Mode extends "many" ? Row[] : Mode extends "one" ? Row : Mode extends "optional" ? Row | null : ExecuteResult;
 export type QueryDefinition<Query extends string = string, Mode extends QueryExecutionMode = QueryExecutionMode> = {
     readonly query: Query;
     readonly mode: Mode;
     readonly queryId: string;
     readonly queryName?: string;
-    run<Queries extends Record<Query, QueryEntry>, FileQueries>(executor: TypedSql<Queries, FileQueries>, ...params: ParamsOf<Queries[Query]>): Promise<QueryModeResult<Mode, RowOf<Queries[Query]>>>;
+    run<Registry extends {
+        queries: Record<Query, NamedQueryEntry>;
+        fileQueries: object;
+    }>(executor: TypedSqlForRegistry<Registry>, params: RegistryParams<Query, Registry>): Promise<QueryResultFor<QueryDefinition<Query, Mode>, Registry>>;
+    run<Registry extends {
+        queries: Record<Query, PositionalQueryEntry>;
+        fileQueries: object;
+    }>(executor: TypedSqlForRegistry<Registry>, ...params: RegistryParams<Query, Registry> & readonly unknown[]): Promise<QueryResultFor<QueryDefinition<Query, Mode>, Registry>>;
 };
 type DefinitionQuery<Definition> = Definition extends QueryDefinition<infer Query, QueryExecutionMode> ? Query : never;
 type DefinitionMode<Definition> = Definition extends QueryDefinition<string, infer Mode> ? Mode : never;
-type RegistryQuery<Definition, Registry extends {
+type RegistryQuery<Query extends string, Registry extends {
+    queries: object;
+}> = Registry["queries"][Query & keyof Registry["queries"]];
+type RegistryParams<Query extends string, Registry extends {
+    queries: object;
+}> = RegistryQuery<Query, Registry>["params" & keyof RegistryQuery<Query, Registry>];
+type RegistryRow<Query extends string, Registry extends {
     queries: object;
-}> = DefinitionQuery<Definition> extends keyof Registry["queries"] ? Registry["queries"][DefinitionQuery<Definition>] : never;
+}> = RegistryQuery<Query, Registry>["row" & keyof RegistryQuery<Query, Registry>];
 export type QueryParamsFor<Definition, Registry extends {
     queries: object;
-}> = RegistryQuery<Definition, Registry> extends {
-    params: infer Params;
-} ? Params : never;
+}> = RegistryParams<DefinitionQuery<Definition>, Registry>;
 export type QueryRowFor<Definition, Registry extends {
     queries: object;
-}> = RowOf<RegistryQuery<Definition, Registry>>;
+}> = RegistryRow<DefinitionQuery<Definition>, Registry>;
 export type QueryResultFor<Definition, Registry extends {
     queries: object;
 }> = QueryModeResult<DefinitionMode<Definition>, QueryRowFor<Definition, Registry>>;

package/dist/src/type-inspection.js

@@ -1,5 +1,16 @@
 import ts from "typescript";
 const unknownTypeCache = new Map();
+function isExistentialJsonParameter(node) {
+    if (!ts.isImportTypeNode(node))
+        return false;
+    if (!ts.isLiteralTypeNode(node.argument) || !ts.isStringLiteral(node.argument.literal))
+        return false;
+    if (node.argument.literal.text !== "@onreza/sqlx-js")
+        return false;
+    if (!node.qualifier || !ts.isIdentifier(node.qualifier) || node.qualifier.text !== "JsonParameter")
+        return false;
+    return node.typeArguments?.length === 1 && node.typeArguments[0]?.kind === ts.SyntaxKind.UnknownKeyword;
+}
 export function containsUnknownType(type) {
     const cached = unknownTypeCache.get(type);
     if (cached !== undefined)
@@ -7,6 +18,8 @@ export function containsUnknownType(type) {
     const source = ts.createSourceFile("sqlx-js-type.ts", `type SqlxJsType = ${type};`, ts.ScriptTarget.Latest, true);
     let found = false;
     const visit = (node) => {
+        if (isExistentialJsonParameter(node))
+            return;
         if (node.kind === ts.SyntaxKind.UnknownKeyword) {
             found = true;
             return;

package/dist/src/typed.d.ts

@@ -1,4 +1,5 @@
 import type { QUERY_EXECUTOR, QueryExecutorMethod } from "./query.js";
+declare const QUERY_REGISTRY: unique symbol;
 type ParamsOf<T> = T extends {
     params: infer P;
 } ? P extends readonly unknown[] ? P : [P] : never[];
@@ -17,21 +18,36 @@ export type TypedFile<TFileQueries> = {
     optional: <P extends keyof TFileQueries>(path: P, ...params: ParamsOf<TFileQueries[P]>) => Promise<RowOf<TFileQueries[P]> | null>;
     execute: <P extends keyof TFileQueries>(path: P, ...params: ParamsOf<TFileQueries[P]>) => Promise<ExecuteResult>;
 };
-export type TypedSql<TQueries, TFileQueries> = {
-    <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>): Promise<RowOf<TQueries[Q]>[]>;
-    one: <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>) => Promise<RowOf<TQueries[Q]>>;
-    optional: <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>) => Promise<RowOf<TQueries[Q]> | null>;
-    execute: <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>) => Promise<ExecuteResult>;
-    file: TypedFile<TFileQueries>;
+export type TypedSqlForRegistry<Registry extends {
+    queries: object;
+    fileQueries: object;
+}> = {
+    <Q extends keyof Registry["queries"]>(query: Q, ...params: ParamsOf<Registry["queries"][Q]>): Promise<RowOf<Registry["queries"][Q]>[]>;
+    one: <Q extends keyof Registry["queries"]>(query: Q, ...params: ParamsOf<Registry["queries"][Q]>) => Promise<RowOf<Registry["queries"][Q]>>;
+    optional: <Q extends keyof Registry["queries"]>(query: Q, ...params: ParamsOf<Registry["queries"][Q]>) => Promise<RowOf<Registry["queries"][Q]> | null>;
+    execute: <Q extends keyof Registry["queries"]>(query: Q, ...params: ParamsOf<Registry["queries"][Q]>) => Promise<ExecuteResult>;
+    file: TypedFile<Registry["fileQueries"]>;
     id: (...parts: string[]) => string;
     json: JsonFn;
     array: ArrayFn;
     readonly [QUERY_EXECUTOR]?: QueryExecutorMethod;
+    readonly [QUERY_REGISTRY]?: Registry;
 };
-export type Typed<TQueries, TFileQueries, TTransactionOptions> = TypedSql<TQueries, TFileQueries> & {
+export type TypedSql<TQueries extends object, TFileQueries extends object> = TypedSqlForRegistry<{
+    queries: TQueries;
+    fileQueries: TFileQueries;
+}>;
+export type TypedForRegistry<Registry extends {
+    queries: object;
+    fileQueries: object;
+}, TTransactionOptions> = TypedSqlForRegistry<Registry> & {
     transaction: {
-        <R>(fn: (tx: TypedSql<TQueries, TFileQueries>) => Promise<R>): Promise<R>;
-        <R>(opts: TTransactionOptions, fn: (tx: TypedSql<TQueries, TFileQueries>) => Promise<R>): Promise<R>;
+        <R>(fn: (tx: TypedSqlForRegistry<Registry>) => Promise<R>): Promise<R>;
+        <R>(opts: TTransactionOptions, fn: (tx: TypedSqlForRegistry<Registry>) => Promise<R>): Promise<R>;
     };
 };
+export type Typed<TQueries extends object, TFileQueries extends object, TTransactionOptions> = TypedForRegistry<{
+    queries: TQueries;
+    fileQueries: TFileQueries;
+}, TTransactionOptions>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onreza/sqlx-js",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by sqlx.",
   "license": "MIT",
   "type": "module",