@jxsuite/connector 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/connector",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Jx database connections and dynamic data tables served over /_jx/data",
   "license": "MIT",
   "repository": {
@@ -57,14 +57,14 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^3.0.0",
+    "@jxsuite/schema": "^4.0.0",
     "kysely": "^0.29.6",
     "kysely-d1": "^0.4.0",
     "kysely-postgres-js": "^5.0.1",
     "postgres": "^3.4.9"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20261002.1",
+    "@cloudflare/workers-types": "^5.20261016.1",
     "ajv": "^8.20.0",
     "hono": "^4.13.13"
   },

package/src/columns.ts

@@ -17,6 +17,10 @@
  * - To-many reference to any other section → JSON text column of id strings
  */
 
+import { isBoolean, isString } from "@jxsuite/schema/guards";
+import type { ColumnDataType } from "kysely";
+import type { JsonValue } from "@jxsuite/schema/types";
+import type { DynamicRow } from "./query.ts";
 import type { TableDef } from "./types.ts";
 
 export type SqlDialectKind = "sqlite" | "postgres";
@@ -28,8 +32,8 @@ export interface RefTarget {
 }
 
 /** Parse a relationship ref pointer, or null when the string is not one. */
-export function parseRefPointer(pointer: unknown): RefTarget | null {
-  if (typeof pointer !== "string") {
+export function parseRefPointer(pointer: JsonValue | undefined): RefTarget | null {
+  if (!isString(pointer)) {
     return null;
   }
   const match = pointer.match(/^#\/([A-Za-z][\w-]*)\/([\w.-]+)$/);
@@ -49,7 +53,7 @@ export interface ColumnSpec {
   /** Physical column name (`<field>_id` for to-one references). */
   column: string;
   /** SQL data type passed to the Kysely schema builder. */
-  dataType: string;
+  dataType: ColumnDataType;
   storage: ColumnStorage;
   /** Set for reference fields (to-one FK columns and to-many JSON id lists). */
   ref: RefTarget | null;
@@ -69,8 +73,8 @@ export interface JunctionSpec {
   sourceColumn: string;
   /** `${targetTable}_id`, suffixed `_2` when the reference is self-referential. */
   targetColumn: string;
-  sourceIdType: string;
-  targetIdType: string;
+  sourceIdType: ColumnDataType;
+  targetIdType: ColumnDataType;
 }
 
 /** The full physical plan for one table. */
@@ -84,12 +88,12 @@ export interface TablePlan {
 }
 
 /** SQL data type of a table's primary key. */
-export function idDataType(idKind: "uuid" | "integer"): string {
+export function idDataType(idKind: "uuid" | "integer"): ColumnDataType {
   return idKind === "uuid" ? "text" : "integer";
 }
 
 /** Map a scalar field schema type to the SQL data type for a dialect. */
-function scalarDataType(type: string | undefined, dialect: SqlDialectKind): string {
+function scalarDataType(type: string | undefined, dialect: SqlDialectKind): ColumnDataType {
   switch (type) {
     case "number": {
       return dialect === "postgres" ? "double precision" : "real";
@@ -240,11 +244,15 @@ export function newRowId(idKind: "uuid" | "integer"): string | undefined {
  * Coerce one JSON payload value to its SQL storage representation.
  *
  * @param {ColumnSpec} spec
- * @param {unknown} value - Already-validated payload value
+ * @param {JsonValue | undefined} value - Already-validated payload value
  * @param {SqlDialectKind} dialect
- * @returns {unknown}
+ * @returns {JsonValue}
  */
-export function toStorage(spec: ColumnSpec, value: unknown, dialect: SqlDialectKind): unknown {
+export function toStorage(
+  spec: ColumnSpec,
+  value: JsonValue | undefined,
+  dialect: SqlDialectKind,
+): JsonValue {
   if (value === null || value === undefined) {
     return null;
   }
@@ -265,24 +273,23 @@ export function toStorage(spec: ColumnSpec, value: unknown, dialect: SqlDialectK
  * Coerce a database row back to its JSON payload shape (booleans, JSON columns).
  *
  * @param {ColumnSpec[]} specs - Column plan of the table
- * @param {Record<string, unknown>} row - Raw row from the driver
- * @returns {Record<string, unknown>}
+ * @param {DynamicRow} row - Raw row from the driver
+ * @returns {DynamicRow}
  */
-export function fromStorage(
-  specs: ColumnSpec[],
-  row: Record<string, unknown>,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = { ...row };
+export function fromStorage(specs: ColumnSpec[], row: DynamicRow) {
+  const out = { ...row };
   for (const spec of specs) {
     const value = out[spec.column];
     if (value === null || value === undefined) {
       continue;
     }
-    if (spec.storage === "boolean" && typeof value !== "boolean") {
-      out[spec.column] = value === 1 || value === "1" || value === true;
-    } else if (spec.storage === "json" && typeof value === "string") {
+    if (spec.storage === "boolean" && !isBoolean(value)) {
+      out[spec.column] = value === 1 || value === "1";
+    } else if (spec.storage === "json" && isString(value)) {
       try {
-        out[spec.column] = JSON.parse(value) as unknown;
+        /* SAFETY: JSON.parse only ever yields JSON values (null, booleans, numbers, strings, arrays
+           and plain objects); a malformed string throws instead and is handled below. */
+        out[spec.column] = JSON.parse(value) as JsonValue;
       } catch {
         // Malformed stored JSON stays a string rather than failing the read.
       }

package/src/connectors.ts

@@ -13,26 +13,35 @@ import { Sqlite } from "./sqlite.ts";
 import { Supabase } from "./supabase.ts";
 import type { Dialect } from "kysely";
 import type { SqlDialectKind } from "./columns.ts";
-import type { ConnectorProvider } from "./provider-utils.ts";
+import type { ConnectorProvider, HostEnv } from "./provider-utils.ts";
 import type { ConnectionDef } from "./types.ts";
 
-export type { ConnectorProvider } from "./provider-utils.ts";
+export type {
+  ConnectorProvider,
+  HostEnv,
+  HostEnvValue,
+  HyperdriveBinding,
+} from "./provider-utils.ts";
 export { tablesForConnection } from "./provider-utils.ts";
 export { D1 } from "./d1.ts";
 export { Sqlite } from "./sqlite.ts";
 export { Supabase } from "./supabase.ts";
 
 /** First-party providers keyed by their `connector.provider` id. */
-export const PROVIDERS: Record<string, ConnectorProvider> = {
+export const PROVIDERS = {
   d1: D1,
   sqlite: Sqlite,
   supabase: Supabase,
-};
+} satisfies Record<string, ConnectorProvider>;
+
+/** True when `id` names one of the first-party providers (own keys only, never prototype members). */
+function isFirstPartyProvider(id: string): id is keyof typeof PROVIDERS {
+  return Object.hasOwn(PROVIDERS, id);
+}
 
 /** The `connections`-bearing slice of a project config. */
 export interface ConnectionsConfig {
   connections?: Record<string, ConnectionDef>;
-  [key: string]: unknown;
 }
 
 /**
@@ -40,20 +49,22 @@ export interface ConnectionsConfig {
  *
  * @param {string} connectionName - Key of the project.json `connections` section
  * @param {ConnectionsConfig} projectConfig - The (partial) project config
- * @param {Record<string, unknown>} env - Host environment (bindings + env vars)
+ * @param {HostEnv} env - Host environment (bindings + env vars)
  * @returns {Promise<{ dialect: Dialect; type: SqlDialectKind }>}
  */
 export async function resolveDialect(
   connectionName: string,
   projectConfig: ConnectionsConfig,
-  env: Record<string, unknown>,
+  env: HostEnv,
 ): Promise<{ dialect: Dialect; type: SqlDialectKind }> {
   const connections = projectConfig.connections ?? {};
   const connection = connections[connectionName];
   if (!connection) {
     throw new Error(`Unknown connection "${connectionName}" (no such connections entry)`);
   }
-  const provider = PROVIDERS[connection.provider];
+  const provider = isFirstPartyProvider(connection.provider)
+    ? PROVIDERS[connection.provider]
+    : undefined;
   if (!provider) {
     throw new Error(
       `Connection "${connectionName}" names unknown provider "${connection.provider}" ` +

package/src/d1.ts

@@ -8,24 +8,29 @@
  * value (specs/extensions.md §13).
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { D1Dialect } from "kysely-d1";
 import { createD1HttpDialect } from "./dialects/d1-http.ts";
 import { deployWithDialect, testWithDialect } from "./provider-utils.ts";
 import type { D1Database } from "@cloudflare/workers-types";
 import type { Dialect } from "kysely";
-import type { ConnectorProvider } from "./provider-utils.ts";
+import type { JsonObject } from "@jxsuite/schema/types";
+import type { ConnectorProvider, HostEnv } from "./provider-utils.ts";
 import type { ConnectionDef } from "./types.ts";
 
 /** Resolve a D1 dialect for a connection (binding first, HTTP API fallback). */
-function d1Dialect(connection: ConnectionDef, env: Record<string, unknown>): Dialect {
+function d1Dialect(connection: ConnectionDef, env: HostEnv): Dialect {
   const { binding, databaseId, $name = "connection" } = connection;
   const bound = binding ? env[binding] : undefined;
   if (bound) {
+    /* SAFETY: a d1 connection's `binding` names the D1 database binding its bindings() fragment
+       provisions (`d1_databases[].binding`), so the env entry under that name is the D1Database
+       the Workers runtime injects; kysely-d1 receives it unchanged. */
     return new D1Dialect({ database: bound as D1Database });
   }
   const apiToken = env["CLOUDFLARE_API_TOKEN"];
   const accountId = connection.accountId ?? env["CLOUDFLARE_ACCOUNT_ID"];
-  if (typeof apiToken === "string" && typeof accountId === "string" && databaseId) {
+  if (isString(apiToken) && isString(accountId) && databaseId) {
     return createD1HttpDialect({ accountId, apiToken, databaseId });
   }
   throw new Error(
@@ -35,26 +40,25 @@ function d1Dialect(connection: ConnectionDef, env: Record<string, unknown>): Dia
 }
 
 export const D1 = {
-  bindings: (connection: ConnectionDef) => ({
-    d1_databases: [
-      {
-        binding: connection.binding ?? "DB",
-        ...(connection.databaseId === undefined ? {} : { database_id: connection.databaseId }),
-        database_name: connection.$name ?? connection.binding ?? "DB",
-      },
-    ],
-  }),
+  bindings: (connection: ConnectionDef) => {
+    const database: JsonObject = { binding: connection.binding ?? "DB" };
+    if (connection.databaseId !== undefined) {
+      database.database_id = connection.databaseId;
+    }
+    database.database_name = connection.$name ?? connection.binding ?? "DB";
+    return { d1_databases: [database] };
+  },
   deploySchema: async (
     tables: Parameters<ConnectorProvider["deploySchema"]>[0],
     connection: ConnectionDef,
-    options: { env: Record<string, unknown>; dryRun?: boolean },
+    options: { env: HostEnv; dryRun?: boolean },
   ) => {
     const dialect = d1Dialect(connection, options.env);
     return deployWithDialect(dialect, "sqlite", tables, { dryRun: options.dryRun ?? false });
   },
   dialect: d1Dialect,
   kind: "sqlite",
-  testConnection: async (connection: ConnectionDef, env: Record<string, unknown>) => {
+  testConnection: async (connection: ConnectionDef, env: HostEnv) => {
     try {
       return await testWithDialect(d1Dialect(connection, env));
     } catch (error) {

package/src/ddl.ts

@@ -11,7 +11,7 @@
 
 import { sql } from "kysely";
 import { idDataType, planTable } from "./columns.ts";
-import type { ColumnDataType, CreateTableBuilder, Kysely } from "kysely";
+import type { CreateTableBuilder, Kysely } from "kysely";
 import type { SqlDialectKind, TablePlan } from "./columns.ts";
 import type { DynamicDatabase } from "./query.ts";
 import type { DeploySchemaResult, TableDef } from "./types.ts";
@@ -27,7 +27,7 @@ const SYSTEM_COLUMNS = new Set(["id", "created_at", "updated_at"]);
 
 interface Executable {
   compile: () => { sql: string };
-  execute: () => Promise<unknown>;
+  execute: () => Promise<void>;
 }
 
 /**
@@ -77,9 +77,7 @@ export async function syncTables(
       for (const col of plan.columns) {
         const current = byName.get(col.column);
         if (!current) {
-          await run(
-            db.schema.alterTable(plan.table).addColumn(col.column, col.dataType as ColumnDataType),
-          );
+          await run(db.schema.alterTable(plan.table).addColumn(col.column, col.dataType));
           continue;
         }
         if (current.dataType.toLowerCase() !== col.dataType.toLowerCase()) {
@@ -112,12 +110,8 @@ export async function syncTables(
         await run(
           db.schema
             .createTable(junction.table)
-            .addColumn(junction.sourceColumn, junction.sourceIdType as ColumnDataType, (c) =>
-              c.notNull(),
-            )
-            .addColumn(junction.targetColumn, junction.targetIdType as ColumnDataType, (c) =>
-              c.notNull(),
-            )
+            .addColumn(junction.sourceColumn, junction.sourceIdType, (c) => c.notNull())
+            .addColumn(junction.targetColumn, junction.targetIdType, (c) => c.notNull())
             .addPrimaryKeyConstraint(`${junction.table}_pk`, [
               junction.sourceColumn,
               junction.targetColumn,
@@ -163,8 +157,8 @@ function buildCreateTable(
   plan: TablePlan,
   dialect: SqlDialectKind,
 ): CreateTableBuilder<string, string> {
-  let builder = db.schema.createTable(plan.table) as CreateTableBuilder<string, string>;
-  const idType = idDataType(plan.idType) as ColumnDataType;
+  let builder: CreateTableBuilder<string, string> = db.schema.createTable(plan.table);
+  const idType = idDataType(plan.idType);
   builder =
     plan.idType === "integer"
       ? builder.addColumn("id", idType, (c) =>
@@ -177,7 +171,7 @@ function buildCreateTable(
     builder = builder.addColumn("created_at", "text").addColumn("updated_at", "text");
   }
   for (const col of plan.columns) {
-    builder = builder.addColumn(col.column, col.dataType as ColumnDataType);
+    builder = builder.addColumn(col.column, col.dataType);
   }
   return builder;
 }

package/src/dialects/bun-sqlite.ts

@@ -63,13 +63,19 @@ async function openDatabase(config: BunSqliteDialectConfig): Promise<{
     // Ensure the parent directory exists (dev-server convention: <project>/.jx/data/).
     const fsSpecifier = "node:fs";
     const pathSpecifier = "node:path";
+    /* SAFETY: the opaque specifier is the literal "node:fs" (kept out of static analysis only so
+       bundles stay inert), and node:fs has exported mkdirSync(path, { recursive }) since Node 10.12
+       and in every Bun release. */
     const fs = (await import(fsSpecifier)) as {
       mkdirSync: (path: string, options: { recursive: boolean }) => void;
     };
+    // SAFETY: the opaque specifier is the literal "node:path", whose dirname(path) returns a string.
     const path = (await import(pathSpecifier)) as { dirname: (path: string) => string };
     fs.mkdirSync(path.dirname(file), { recursive: true });
   }
   const sqliteSpecifier = "bun:sqlite";
+  /* SAFETY: the opaque specifier is the literal "bun:sqlite", whose Database class opens a file
+     path and structurally satisfies BunSqliteDatabaseLike (prepare/close are a subset of it). */
   const sqlite = (await import(sqliteSpecifier)) as {
     Database: new (file: string) => BunSqliteDatabaseLike;
   };
@@ -88,8 +94,13 @@ function createDriver(config: BunSqliteDialectConfig): Driver {
       }
       const { sql, parameters } = compiledQuery;
       const stmt = db.prepare(sql);
+      /* SAFETY: the parameters are the values this connector's queries bind (toStorage output,
+         ids, filter probes and timestamps: strings, numbers, booleans, bigints and null), every
+         one of which bun:sqlite accepts as a SQLQueryBindings entry. */
       const bindings = parameters as SQLQueryBindings[];
       if (stmt.columnNames.length > 0) {
+        /* SAFETY: Kysely instantiates R with the row shape of the compiled select, and
+           Statement.all() returns one plain object per result row keyed by column name. */
         return { rows: stmt.all(...bindings) as R[] };
       }
       const info = stmt.run(...bindings);

package/src/dialects/d1-http.ts

@@ -9,6 +9,7 @@
 
 import { SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler } from "kysely";
 import type { CompiledQuery, DatabaseConnection, Dialect, Driver, QueryResult } from "kysely";
+import type { JsonObject } from "@jxsuite/schema/types";
 
 export interface D1HttpDialectConfig {
   accountId: string;
@@ -25,11 +26,18 @@ interface D1HttpResponse {
   errors?: { code?: number; message?: string }[];
   result?: {
     success?: boolean;
-    results?: Record<string, unknown>[];
+    results?: JsonObject[];
     meta?: { changes?: number; last_row_id?: number };
   }[];
 }
 
+/** A QueryResult under construction: Kysely's own interface declares its fields readonly. */
+interface D1HttpQueryResult<R> {
+  insertId?: bigint;
+  numAffectedRows?: bigint;
+  rows: R[];
+}
+
 /**
  * Create the Kysely dialect over the D1 HTTP API.
  *
@@ -62,6 +70,9 @@ async function executeHttp<R>(
     },
     method: "POST",
   });
+  /* SAFETY: Cloudflare's v4 API answers with its { success, errors, result } envelope (or the catch
+     turns an unparsable body into null); every field below is read optionally, and a body without
+     `success: true` is rejected before `result` is touched. */
   const body = (await response.json().catch(() => null)) as D1HttpResponse | null;
   if (!response.ok || !body?.success) {
     const detail =
@@ -73,11 +84,16 @@ async function executeHttp<R>(
   }
   const [result] = body.result ?? [];
   const meta = result?.meta ?? {};
-  return {
-    ...(meta.last_row_id === undefined ? {} : { insertId: BigInt(meta.last_row_id) }),
-    ...(meta.changes === undefined ? {} : { numAffectedRows: BigInt(meta.changes) }),
-    rows: (result?.results ?? []) as R[],
-  };
+  /* SAFETY: Kysely instantiates R with the row shape of the compiled statement, and the D1 query
+     endpoint returns each result row as a JSON object keyed by column name. */
+  const queryResult: D1HttpQueryResult<R> = { rows: (result?.results ?? []) as R[] };
+  if (meta.last_row_id !== undefined) {
+    queryResult.insertId = BigInt(meta.last_row_id);
+  }
+  if (meta.changes !== undefined) {
+    queryResult.numAffectedRows = BigInt(meta.changes);
+  }
+  return queryResult;
 }
 
 /** Build the stateless HTTP driver. */

package/src/provider-utils.ts

@@ -9,25 +9,43 @@
 
 import { Kysely, sql } from "kysely";
 import { syncTables } from "./ddl.ts";
+import type { D1Database } from "@cloudflare/workers-types";
 import type { Dialect } from "kysely";
+import type { JsonObject } from "@jxsuite/schema/types";
 import type { SqlDialectKind } from "./columns.ts";
 import type { DynamicDatabase } from "./query.ts";
 import type { ConnectionDef, DeploySchemaResult, TableDef, TestConnectionResult } from "./types.ts";
 
+/** A Hyperdrive binding as the Supabase provider reads it: only its pooled connection string. */
+export interface HyperdriveBinding {
+  readonly connectionString: string;
+}
+
+/**
+ * One host environment entry: an env var or secret (a string), or a platform binding a connection
+ * names through its `binding` field (a D1 database, a Hyperdrive config).
+ */
+export type HostEnvValue = string | D1Database | HyperdriveBinding;
+
+/**
+ * The host environment a connection resolves against: process.env merged under `.dev.vars` plus
+ * `JX_PROJECT_ROOT` on node/Bun hosts, or the Worker `env` (vars, secrets and bindings) on
+ * Cloudflare. Connections carry identifiers only; every secret and binding is read from here.
+ */
+export type HostEnv = Readonly<Record<string, HostEnvValue | undefined>>;
+
 /** The static capability surface of a connector provider implementation. */
 export interface ConnectorProvider {
   kind: SqlDialectKind;
-  dialect: (connection: ConnectionDef, env: Record<string, unknown>) => Dialect | Promise<Dialect>;
+  dialect: (connection: ConnectionDef, env: HostEnv) => Dialect | Promise<Dialect>;
   deploySchema: (
     tables: Record<string, TableDef>,
     connection: ConnectionDef,
-    options: { env: Record<string, unknown>; dryRun?: boolean },
+    options: { env: HostEnv; dryRun?: boolean },
   ) => Promise<DeploySchemaResult>;
-  bindings: (connection: ConnectionDef) => Record<string, unknown>;
-  testConnection: (
-    connection: ConnectionDef,
-    env: Record<string, unknown>,
-  ) => Promise<TestConnectionResult>;
+  /** The wrangler binding fragment this connection provisions (`jx db push` patches wrangler.jsonc). */
+  bindings: (connection: ConnectionDef) => JsonObject;
+  testConnection: (connection: ConnectionDef, env: HostEnv) => Promise<TestConnectionResult>;
 }
 
 /**
@@ -76,11 +94,7 @@ export function tablesForConnection(
   tables: Record<string, TableDef>,
   connectionName: string,
 ): Record<string, TableDef> {
-  const out: Record<string, TableDef> = {};
-  for (const [name, def] of Object.entries(tables)) {
-    if (def.connection === connectionName) {
-      out[name] = def;
-    }
-  }
-  return out;
+  return Object.fromEntries(
+    Object.entries(tables).filter(([, def]) => def.connection === connectionName),
+  );
 }

package/src/query.ts

@@ -9,42 +9,61 @@
  * empty.
  */
 
+import { isBoolean, isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
 import type { ExpressionBuilder, ExpressionWrapper, SelectQueryBuilder, SqlBool } from "kysely";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
 import type { ColumnSpec } from "./columns.ts";
 
-/** One filter rule of the shared content grammar. */
+/**
+ * One filter rule of the shared content grammar. Rules arrive as wire JSON, and normalization only
+ * requires a string `field`: an absent or unrecognized `op` matches everything (see
+ * ruleExpression).
+ */
 export interface FilterRule {
   field: string;
-  op: string;
-  value?: unknown;
+  op?: JsonValue;
+  value?: JsonValue;
 }
 
+/** One sort rule; any `order` other than "desc" sorts ascending. */
 export interface SortRule {
   field: string;
-  order?: string;
+  order?: JsonValue;
 }
 
-/** Loosely-typed database shape for dynamic tables (columns are only known at runtime). */
-export type DynamicDatabase = Record<string, Record<string, unknown>>;
+/**
+ * A value a SQL driver reads or binds: JSON scalars and structures (postgres json columns, arrays),
+ * 64-bit integers, blobs and timestamps.
+ */
+export type SqlValue = JsonValue | bigint | Uint8Array | Date;
+
+/** One dynamic-table row keyed by physical column name (columns are only known at runtime). */
+export type DynamicRow = Record<string, SqlValue>;
+
+/** Database shape for dynamic tables: every table is a bag of runtime-known columns. */
+export type DynamicDatabase = Record<string, DynamicRow>;
 
-type DynamicSelect = SelectQueryBuilder<DynamicDatabase, string, Record<string, unknown>>;
+type DynamicSelect = SelectQueryBuilder<DynamicDatabase, string, DynamicRow>;
 type DynamicEb = ExpressionBuilder<DynamicDatabase, string>;
 type BoolExpr = ExpressionWrapper<DynamicDatabase, string, SqlBool>;
 
+/** A wire rule object naming a string `field` — the one requirement filter and sort rules share. */
+function isFieldRule(rule: JsonValue): rule is JsonObject & { field: string } {
+  return isJsonObject(rule) && isString(rule.field);
+}
+
 /**
  * Normalize a wire filter (rule array or equality-object shorthand) into rules.
  *
- * @param {unknown} filter
+ * @param {JsonValue | undefined} filter
  * @returns {FilterRule[]}
  */
-export function normalizeFilter(filter: unknown): FilterRule[] {
+export function normalizeFilter(filter: JsonValue | undefined): FilterRule[] {
   if (Array.isArray(filter)) {
-    return (filter as FilterRule[]).filter(
-      (rule) => rule && typeof rule === "object" && typeof rule.field === "string",
-    );
+    return filter.filter((rule) => isFieldRule(rule));
   }
-  if (filter && typeof filter === "object") {
-    return Object.entries(filter as Record<string, unknown>).map(([field, value]) => ({
+  if (isJsonObject(filter)) {
+    return Object.entries(filter).map(([field, value]) => ({
       field,
       op: "==",
       value,
@@ -54,11 +73,9 @@ export function normalizeFilter(filter: unknown): FilterRule[] {
 }
 
 /** Normalize a wire sort (single rule or list) into rules. */
-export function normalizeSort(sort: unknown): SortRule[] {
+export function normalizeSort(sort: JsonValue | undefined): SortRule[] {
   const list = Array.isArray(sort) ? sort : sort ? [sort] : [];
-  return (list as SortRule[]).filter(
-    (rule) => rule && typeof rule === "object" && typeof rule.field === "string",
-  );
+  return list.filter((rule) => isFieldRule(rule));
 }
 
 /** Resolve a grammar field name to its physical column (`author` → `author_id` for refs). */
@@ -140,13 +157,13 @@ function ruleExpression(
     }
     default: {
       // Unknown ops match everything, like the in-memory evaluator.
-      return eb.lit(true as SqlBool);
+      return eb.lit<SqlBool>(true);
     }
   }
 }
 
 /** LIKE pattern for `contains`: JSON columns match the JSON-encoded element. */
-function containsPattern(spec: ColumnSpec | null, value: unknown): string {
+function containsPattern(spec: ColumnSpec | null, value: JsonValue | undefined): string {
   if (spec?.storage === "json") {
     const encoded = JSON.stringify(value);
     return `%${escapeLike(encoded)}%`;
@@ -160,7 +177,7 @@ function escapeLike(text: string): string {
 }
 
 /** Coerce a filter probe value to the column's storage representation. */
-function storageValue(spec: ColumnSpec | null, value: unknown): string | number {
+function storageValue(spec: ColumnSpec | null, value: JsonValue | undefined): string | number {
   if (spec?.storage === "boolean") {
     const truthy = value === true || value === "true" || value === 1 || value === "1";
     return truthy ? 1 : 0;
@@ -168,10 +185,10 @@ function storageValue(spec: ColumnSpec | null, value: unknown): string | number
   if (spec?.storage === "json") {
     return JSON.stringify(value);
   }
-  if (typeof value === "number") {
+  if (isNumber(value)) {
     return value;
   }
-  if (typeof value === "boolean") {
+  if (isBoolean(value)) {
     return value ? 1 : 0;
   }
   return String(value);