okengine 0.15.2 → 0.16.0

package/src/elements/store/schema-decl.ts

@@ -38,8 +38,14 @@ export interface ColumnReference {
  * `getSQL` is a structural bridge so drizzle-orm operators (`eq`, `isNull`, …)
  * accept abstract columns in TypeScript. OKE’s SQL compiler never calls it —
  * it reads {@link SchemaColumnDecl.sqlName} / metadata directly.
+ *
+ * `TData` / `TNotNull` are type-level only (`$infer` is a phantom). They let
+ * {@link InferColumnJs} / table `$inferSelect` resolve real row shapes.
  */
-export interface SchemaColumnDecl extends ColumnDef {
+export interface SchemaColumnDecl<
+  TData = unknown,
+  TNotNull extends boolean = boolean,
+> extends ColumnDef {
   /** JS object key (e.g. `createdAt`). */
   readonly key: string;
   /** Database column name (e.g. `created_at`). */
@@ -47,7 +53,12 @@ export interface SchemaColumnDecl extends ColumnDef {
   /** Declared SQL type. */
   readonly sqlType: FieldSqlType;
   readonly primaryKey: boolean;
-  readonly notNull: boolean;
+  readonly notNull: TNotNull;
+  /**
+   * Phantom JS value type — not present at runtime. Distinguishes `string`
+   * vs `number` so structural typing does not collapse column data types.
+   */
+  readonly $infer?: TData;
   readonly unique: boolean;
   /** Literal `.default(v)` when set. */
   readonly defaultValue?: string | number | boolean | null;
@@ -120,33 +131,41 @@ export interface SchemaTableDecl extends TableHandle {
   readonly policies?: readonly SchemaPolicyDecl[];
 }
 
-/** Fluent field builder before key finalization. */
-export interface FieldBuilder {
-  primaryKey(): FieldBuilder;
-  notNull(): FieldBuilder;
-  unique(): FieldBuilder;
-  default(value: string | number | boolean | null): FieldBuilder;
-  defaultFn(fn: () => unknown): FieldBuilder;
-  pii(): FieldBuilder;
-  sensitive(): FieldBuilder;
-  retain(duration: string): FieldBuilder;
+/**
+ * Fluent field builder before key finalization.
+ *
+ * `TData` is the JS value type (`string` / `number`). `TNotNull` is `true`
+ * after `.notNull()` or `.primaryKey()` — matching runtime finalize.
+ */
+export interface FieldBuilder<TData = unknown, TNotNull extends boolean = false> {
+  primaryKey(): FieldBuilder<TData, true>;
+  notNull(): FieldBuilder<TData, true>;
+  unique(): FieldBuilder<TData, TNotNull>;
+  default(value: string | number | boolean | null): FieldBuilder<TData, TNotNull>;
+  defaultFn(fn: () => unknown): FieldBuilder<TData, TNotNull>;
+  pii(): FieldBuilder<TData, TNotNull>;
+  sensitive(): FieldBuilder<TData, TNotNull>;
+  retain(duration: string): FieldBuilder<TData, TNotNull>;
   /** Override snake_case SQL name. */
-  as(sqlName: string): FieldBuilder;
+  as(sqlName: string): FieldBuilder<TData, TNotNull>;
   /** Optional human description for Console / docs (falls back to the JS key). */
-  describe(description: string): FieldBuilder;
+  describe(description: string): FieldBuilder<TData, TNotNull>;
   /**
    * Declare a foreign key to another column (dialect-agnostic).
    *
    * @param ref - Lazy target column (`() => links.code`)
    * @param actions - Optional ON DELETE / ON UPDATE
    */
-  references(ref: () => SchemaColumnDecl, actions?: ReferenceActions): FieldBuilder;
+  references(
+    ref: () => SchemaColumnDecl,
+    actions?: ReferenceActions,
+  ): FieldBuilder<TData, TNotNull>;
   /**
    * Bind the JS key and produce a {@link SchemaColumnDecl}.
    *
    * @param key - Object key in the table column map
    */
-  finalize(key: string): SchemaColumnDecl;
+  finalize(key: string): SchemaColumnDecl<TData, TNotNull>;
 }
 
 interface FieldState {
@@ -186,31 +205,39 @@ function mergeClassification(
   return { ...(current ?? {}), ...patch };
 }
 
-function createBuilder(state: FieldState): FieldBuilder {
-  const next = (patch: Partial<FieldState>): FieldBuilder => createBuilder({ ...state, ...patch });
+function createBuilder<TData, TNotNull extends boolean>(
+  state: FieldState,
+): FieldBuilder<TData, TNotNull> {
+  const next = <N extends boolean>(patch: Partial<FieldState>): FieldBuilder<TData, N> =>
+    createBuilder<TData, N>({ ...state, ...patch });
 
   return {
-    primaryKey: () => next({ primaryKey: true, notNull: true }),
-    notNull: () => next({ notNull: true }),
-    unique: () => next({ unique: true }),
-    default: (value) => next({ defaultValue: value }),
+    primaryKey: () => next<true>({ primaryKey: true, notNull: true }),
+    notNull: () => next<true>({ notNull: true }),
+    unique: () => next<TNotNull>({ unique: true }),
+    default: (value) => next<TNotNull>({ defaultValue: value }),
     defaultFn: (fn) =>
-      next({
+      next<TNotNull>({
         defaultFn: fn,
         defaultFnKind: defaultFnKindOf(fn),
       }),
-    pii: () => next({ classification: mergeClassification(state.classification, { pii: true }) }),
+    pii: () =>
+      next<TNotNull>({ classification: mergeClassification(state.classification, { pii: true }) }),
     sensitive: () =>
-      next({ classification: mergeClassification(state.classification, { sensitive: true }) }),
+      next<TNotNull>({
+        classification: mergeClassification(state.classification, { sensitive: true }),
+      }),
     retain: (duration) =>
-      next({ classification: mergeClassification(state.classification, { retain: duration }) }),
-    as: (sqlName) => next({ sqlName }),
-    describe: (description) => next({ description }),
+      next<TNotNull>({
+        classification: mergeClassification(state.classification, { retain: duration }),
+      }),
+    as: (sqlName) => next<TNotNull>({ sqlName }),
+    describe: (description) => next<TNotNull>({ description }),
     references: (ref, actions) =>
-      next({
+      next<TNotNull>({
         references: actions ? { ref, actions } : { ref },
       }),
-    finalize(key: string): SchemaColumnDecl {
+    finalize(key: string): SchemaColumnDecl<TData, TNotNull> {
       const sqlName = state.sqlName ?? camelToSnake(key);
       return {
         key,
@@ -218,7 +245,7 @@ function createBuilder(state: FieldState): FieldBuilder {
         sqlName,
         sqlType: state.sqlType,
         primaryKey: state.primaryKey,
-        notNull: state.notNull || state.primaryKey,
+        notNull: (state.notNull || state.primaryKey) as TNotNull,
         unique: state.unique,
         ...(state.defaultValue !== undefined ? { defaultValue: state.defaultValue } : {}),
         ...(state.defaultFn ? { defaultFn: state.defaultFn } : {}),
@@ -240,15 +267,15 @@ function createBuilder(state: FieldState): FieldBuilder {
  * Field builders — `field.text()` / `field.integer()`.
  */
 export const field = {
-  text: (): FieldBuilder =>
-    createBuilder({
+  text: (): FieldBuilder<string, false> =>
+    createBuilder<string, false>({
       sqlType: "text",
       primaryKey: false,
       notNull: false,
       unique: false,
     }),
-  integer: (): FieldBuilder =>
-    createBuilder({
+  integer: (): FieldBuilder<number, false> =>
+    createBuilder<number, false>({
       sqlType: "integer",
       primaryKey: false,
       notNull: false,
@@ -256,8 +283,19 @@ export const field = {
     }),
 } as const;
 
-/** Column map input for {@link schemaTable}. */
-export type SchemaColumnInput = FieldBuilder | SchemaColumnDecl;
+/**
+ * Column map input for {@link schemaTable}.
+ *
+ * Explicit `string` / `number` × nullability variants so `field.text()`
+ * (`FieldBuilder<string, false>`) remains assignable — methodful builders
+ * are invariant in their type parameters.
+ */
+export type SchemaColumnInput =
+  | FieldBuilder<string, false>
+  | FieldBuilder<string, true>
+  | FieldBuilder<number, false>
+  | FieldBuilder<number, true>
+  | SchemaColumnDecl;
 
 /**
  * Whether a value is a finalized {@link SchemaColumnDecl}.
@@ -301,7 +339,7 @@ export function finalizeColumnMap(
 ): Record<string, SchemaColumnDecl> {
   const out: Record<string, SchemaColumnDecl> = {};
   for (const [key, value] of Object.entries(columns)) {
-    out[key] = isFieldBuilder(value) ? value.finalize(key) : value;
+    out[key] = isFieldBuilder(value) ? value.finalize(key) : (value as SchemaColumnDecl);
   }
   return out;
 }
@@ -333,14 +371,34 @@ export function schemaTableSqlName(table: SchemaTableDecl): string | undefined {
   return undefined;
 }
 
+/**
+ * JS value type for a finalized column (`string` / `number`, plus `| null`
+ * when the column is nullable).
+ */
+export type InferColumnJs<C> =
+  C extends SchemaColumnDecl<infer D, infer N> ? (N extends true ? D : D | null) : unknown;
+
+/**
+ * Finalize a {@link schemaTable} column input into a typed decl.
+ */
+export type FinalizeColumn<T> =
+  T extends FieldBuilder<infer D, infer N>
+    ? SchemaColumnDecl<D, N>
+    : T extends SchemaColumnDecl<infer D, infer N>
+      ? SchemaColumnDecl<D, N>
+      : SchemaColumnDecl;
+
 /**
  * Table decl with columns as own properties (`links.code`) for FK / relations.
+ *
+ * `$inferSelect` is type-level only (Drizzle's own alias) — not set at runtime.
  */
 export type SchemaTableWithColumns<
   C extends Record<string, SchemaColumnDecl> = Record<string, SchemaColumnDecl>,
 > = Omit<SchemaTableDecl, "columns"> & {
   readonly columns: Readonly<C>;
-} & Omit<C, "kind" | "tableName">;
+  readonly $inferSelect: { [K in keyof C]: InferColumnJs<C[K]> };
+} & Omit<C, "kind" | "tableName" | "$inferSelect">;
 
 /**
  * Declare an abstract schema table (ORM-agnostic).
@@ -356,7 +414,7 @@ export function schemaTable<C extends Record<string, SchemaColumnInput>>(
   name: string,
   columns: C,
   extras: readonly SchemaTableExtra[] = [],
-): SchemaTableWithColumns<{ [K in keyof C]: SchemaColumnDecl }> {
+): SchemaTableWithColumns<{ [K in keyof C]: FinalizeColumn<C[K]> }> {
   const finalized = finalizeColumnMap(columns);
   const stamped: Record<string, SchemaColumnDecl> = {};
   for (const [key, col] of Object.entries(finalized)) {
@@ -377,7 +435,7 @@ export function schemaTable<C extends Record<string, SchemaColumnInput>>(
   // the table discriminant / SQL name).
   Object.defineProperty(table, "kind", { value: "schema-table", enumerable: false });
   Object.defineProperty(table, "tableName", { value: name, enumerable: false });
-  return table as SchemaTableWithColumns<{ [K in keyof C]: SchemaColumnDecl }>;
+  return table as SchemaTableWithColumns<{ [K in keyof C]: FinalizeColumn<C[K]> }>;
 }
 
 /**

package/src/elements/store/sql-select.types.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Type-level proof: `select().from(store.schema.table())` resolves to the
+ * declared column JS shape — not `SqlRow`.
+ */
+import { describe, expect, test } from "bun:test";
+
+import type { SqlRow } from "../../drivers/types.ts";
+import { field, schemaTable } from "./schema-decl.ts";
+import type { InferSelectRow, SqlStoreHandle } from "./sql-session.ts";
+import { defineTable } from "./table.ts";
+
+/** Compile-time equality. */
+type Eq<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Assert<T extends true> = T;
+
+const items = schemaTable("items", {
+  id: field.text().primaryKey(),
+  title: field.text().notNull(),
+  note: field.text(),
+  count: field.integer().notNull(),
+  score: field.integer(),
+});
+
+type ExpectedRow = {
+  id: string;
+  title: string;
+  note: string | null;
+  count: number;
+  score: number | null;
+};
+
+async function selectAll(db: SqlStoreHandle) {
+  return db.select().from(items);
+}
+
+async function selectWhere(db: SqlStoreHandle) {
+  return db.select().from(items).where({ id: "x" });
+}
+
+async function selectOrder(db: SqlStoreHandle) {
+  return db.select().from(items).orderBy(items.title);
+}
+
+async function selectLimit(db: SqlStoreHandle) {
+  return db.select().from(items).limit(1);
+}
+
+async function selectProj(db: SqlStoreHandle) {
+  return db.select({ title: items.title }).from(items);
+}
+
+const bare = defineTable("bare", { id: { name: "id" } });
+
+async function selectBare(db: SqlStoreHandle) {
+  return db.select().from(bare);
+}
+
+type _Infer = Assert<Eq<InferSelectRow<typeof items>, ExpectedRow>>;
+type _All = Assert<Eq<Awaited<ReturnType<typeof selectAll>>, ExpectedRow[]>>;
+type _Where = Assert<Eq<Awaited<ReturnType<typeof selectWhere>>, ExpectedRow[]>>;
+type _Order = Assert<Eq<Awaited<ReturnType<typeof selectOrder>>, ExpectedRow[]>>;
+type _Limit = Assert<Eq<Awaited<ReturnType<typeof selectLimit>>, ExpectedRow[]>>;
+type _Proj = Assert<Eq<Awaited<ReturnType<typeof selectProj>>, SqlRow[]>>;
+type _Bare = Assert<Eq<Awaited<ReturnType<typeof selectBare>>, SqlRow[]>>;
+
+describe("select().from() row inference", () => {
+  test("type-level row shape matches declared columns", () => {
+    const _keep: _Infer & _All & _Where & _Order & _Limit & _Proj & _Bare = true;
+    expect(_keep).toBe(true);
+  });
+});

package/src/elements/store/sql-session.ts

@@ -34,6 +34,15 @@ import {
 
 export type { WhereMap } from "./sql-condition.ts";
 
+/**
+ * Inferred select-row shape for a table handle.
+ *
+ * Uses `$inferSelect` when present (OKE `store.schema.table()` and Drizzle
+ * `pgTable()` / `sqliteTable()`). Bare {@link TableHandle} / `unknown` stay
+ * {@link SqlRow}.
+ */
+export type InferSelectRow<T> = T extends { readonly $inferSelect: infer R } ? R : SqlRow;
+
 /** Serialize stamp frames on a shared connection so concurrent identities cannot interleave. */
 const rlsStampTails = new WeakMap<SqlConnection, Promise<unknown>>();
 
@@ -97,44 +106,44 @@ export interface SqlSessionOptions {
  * Continuations after `.orderBy(...)` — awaitable, optional `.limit` /
  * `.offset`.
  */
-export interface SelectOrderBuilder extends PromiseLike<SqlRow[]> {
+export interface SelectOrderBuilder<TRow = SqlRow> extends PromiseLike<TRow[]> {
   /**
    * Cap the number of returned rows.
    *
    * @param n - Max rows
    */
-  limit(n: number): Promise<SqlRow[]>;
+  limit(n: number): Promise<TRow[]>;
   /**
    * Skip the first `n` rows (`LIMIT … OFFSET …`).
    *
    * @param n - Rows to skip
    */
-  offset(n: number): Promise<SqlRow[]>;
+  offset(n: number): Promise<TRow[]>;
 }
 
 /**
  * Continuations after `.where(...)` on a select — awaitable, optional
  * `.orderBy(...)` / `.limit(...)` / `.offset(...)`.
  */
-export interface SelectWhereBuilder extends PromiseLike<SqlRow[]> {
+export interface SelectWhereBuilder<TRow = SqlRow> extends PromiseLike<TRow[]> {
   /**
    * Order rows with Drizzle `asc()` / `desc()` terms.
    *
    * @param orders - Order terms
    */
-  orderBy(...orders: readonly unknown[]): SelectOrderBuilder;
+  orderBy(...orders: readonly unknown[]): SelectOrderBuilder<TRow>;
   /**
    * Cap the number of returned rows.
    *
    * @param n - Max rows
    */
-  limit(n: number): Promise<SqlRow[]>;
+  limit(n: number): Promise<TRow[]>;
   /**
    * Skip the first `n` rows.
    *
    * @param n - Rows to skip
    */
-  offset(n: number): Promise<SqlRow[]>;
+  offset(n: number): Promise<TRow[]>;
 }
 
 /**
@@ -142,42 +151,49 @@ export interface SelectWhereBuilder extends PromiseLike<SqlRow[]> {
  * `.where(...)` / `.orderBy(...)` / `.limit(...)` / `.offset(...)` in any
  * order.
  */
-export interface SelectFromBuilder extends PromiseLike<SqlRow[]> {
+export interface SelectFromBuilder<TRow = SqlRow> extends PromiseLike<TRow[]> {
   /**
    * Filter with a plain equality map or a Drizzle SQL condition
    * (`eq`, `and`, `or`, `lt`, `like`, …).
    *
    * @param where - Condition
    */
-  where(where: unknown): SelectWhereBuilder;
+  where(where: unknown): SelectWhereBuilder<TRow>;
   /**
    * Order rows with Drizzle `asc()` / `desc()` terms.
    *
    * @param orders - Order terms
    */
-  orderBy(...orders: readonly unknown[]): SelectOrderBuilder;
+  orderBy(...orders: readonly unknown[]): SelectOrderBuilder<TRow>;
   /**
    * Cap the number of returned rows.
    *
    * @param n - Max rows
    */
-  limit(n: number): Promise<SqlRow[]>;
+  limit(n: number): Promise<TRow[]>;
   /**
    * Skip the first `n` rows.
    *
    * @param n - Rows to skip
    */
-  offset(n: number): Promise<SqlRow[]>;
+  offset(n: number): Promise<TRow[]>;
 }
 
-/** Fluent select builder. */
-export interface SelectBuilder {
+/**
+ * Fluent select builder.
+ *
+ * `TLocked` is `undefined` for `select()` (row type inferred from `.from`)
+ * and {@link SqlRow} for `select({ alias: col })` projections.
+ */
+export interface SelectBuilder<TLocked extends SqlRow | undefined = undefined> {
   /**
    * Choose the source table.
    *
    * @param table - Table handle or Drizzle table
    */
-  from(table: TableHandle | unknown): SelectFromBuilder;
+  from<TTable>(
+    table: TTable,
+  ): SelectFromBuilder<TLocked extends undefined ? InferSelectRow<TTable> : TLocked>;
 }
 
 /** Fluent insert builder. */
@@ -244,12 +260,13 @@ export interface SqlStoreHandle {
   /** Underlying driver id. */
   readonly driverId: SqlConnection["driverId"];
   /**
-   * Start a select. Optional column map projects / aliases columns
-   * (`select({ clicks: links.clicks })`).
+   * Start a select. No-arg form infers the row from `.from(table)`.
+   * A column map (`select({ clicks: links.clicks })`) stays {@link SqlRow}.
    *
    * @param columns - Optional `{ alias: drizzleColumn }` map
    */
-  select(columns?: unknown): SelectBuilder;
+  select(): SelectBuilder<undefined>;
+  select(columns: unknown): SelectBuilder<SqlRow>;
   /**
    * Start an insert into `table`.
    *
@@ -600,20 +617,20 @@ export function createSqlStoreHandle(
     };
   }
 
-  const handle: SqlStoreHandle = {
+  const handle = {
     ref,
     routedRole: options.routedRole,
     driverId: connection.driverId,
 
-    select(columns?) {
+    select(columns?: unknown) {
       return {
-        from(table) {
+        from(table: TableHandle | unknown) {
           return selectFrom(table, columns);
         },
       };
     },
 
-    insert(table): InsertBuilder {
+    insert(table: TableHandle | unknown): InsertBuilder {
       const name = resolveTableName(table);
       return {
         values(row) {
@@ -648,7 +665,7 @@ export function createSqlStoreHandle(
       };
     },
 
-    update(table): UpdateBuilder {
+    update(table: TableHandle | unknown): UpdateBuilder {
       const name = resolveTableName(table);
       return {
         set(row) {
@@ -675,7 +692,7 @@ export function createSqlStoreHandle(
       };
     },
 
-    async findById(table, idValue) {
+    async findById(table: TableHandle | unknown, idValue: string) {
       await ensureFromMeta(table);
       const name = resolveTableName(table);
       const pk = resolvePkColumn(table);
@@ -716,7 +733,7 @@ export function createSqlStoreHandle(
       return builder;
     }) as SqlStoreHandle["delete"],
 
-    async exists(table, idOrWhere) {
+    async exists(table: TableHandle | unknown, idOrWhere: string | WhereMap) {
       await ensureFromMeta(table);
       const name = resolveTableName(table);
       const where: WhereMap =
@@ -734,7 +751,12 @@ export function createSqlStoreHandle(
       return rows.length > 0;
     },
 
-    async upsert(table, matchOn, values, upsertOptions) {
+    async upsert(
+      table: TableHandle | unknown,
+      matchOn: WhereMap | unknown,
+      values: SqlRow,
+      upsertOptions?: { readonly onExisting?: "update" },
+    ) {
       await ensureFromMeta(table);
       const name = resolveTableName(table);
       const compiled = compileTableWhere(table, matchOn);
@@ -766,7 +788,7 @@ export function createSqlStoreHandle(
       return { status: "changed" as const };
     },
 
-    async increment(table, idValue, column, by = 1) {
+    async increment(table: TableHandle | unknown, idValue: string, column: string, by = 1) {
       await ensureFromMeta(table);
       const name = resolveTableName(table);
       const pk = resolvePkColumn(table);
@@ -785,7 +807,7 @@ export function createSqlStoreHandle(
       return asNumber(row[sqlCol], sqlCol);
     },
 
-    async raw(sql, params = []) {
+    async raw(sql: string, params: readonly unknown[] = []) {
       const table = tableFromSql(sql);
       // Memory SQL (console-next seed) implements DML on `exec`, not `query`.
       // SELECT / RETURNING still go through `query` so callers get rows.
@@ -797,7 +819,7 @@ export function createSqlStoreHandle(
       return mask(rows, table);
     },
 
-    async count(table, where) {
+    async count(table: TableHandle | unknown, where?: unknown) {
       await ensureFromMeta(table);
       const name = resolveTableName(table);
       let sql = `SELECT COUNT(*) AS "count" FROM ${quoteIdent(name)}`;
@@ -813,7 +835,7 @@ export function createSqlStoreHandle(
       return asNumber(rows[0]?.count ?? rows[0]?.COUNT ?? 0, "count");
     },
 
-    async page(table, options) {
+    async page(table: TableHandle | unknown, options: SqlPageOptions) {
       if (options.after !== undefined && options.before !== undefined) {
         throw new Error("page(): after and before (keyset) cannot combine");
       }
@@ -838,7 +860,7 @@ export function createSqlStoreHandle(
       });
     },
 
-    async ensureTable(table) {
+    async ensureTable(table: TableHandle) {
       const cols = Object.values(table.columns);
       const pk = resolvePkColumn(table);
       const intType =
@@ -863,7 +885,7 @@ export function createSqlStoreHandle(
     },
   };
 
-  return handle;
+  return handle as SqlStoreHandle;
 }
 
 /**

package/src/elements/store.ts

@@ -47,6 +47,8 @@ export type {
   SchemaColumnInput,
   SchemaTableDecl,
   SchemaTableWithColumns,
+  InferColumnJs,
+  FinalizeColumn,
   SchemaRelationsDecl,
   SchemaPolicyDecl,
   SchemaTableExtra,
@@ -121,6 +123,7 @@ export type {
   SelectFromBuilder,
   SelectWhereBuilder,
   SelectOrderBuilder,
+  InferSelectRow,
   InsertBuilder,
   InsertValuesBuilder,
   SqlSessionOptions,

package/src/index.ts

@@ -62,6 +62,7 @@ export {
   type StoreDecl,
   type StoreRuntime,
   type SqlStoreHandle,
+  type InferSelectRow,
   type TableHandle,
   type SchemaTableDecl,
   type SchemaColumnDecl,