@zeno-lib/db 0.3.1 → 0.4.0

package/src/query.test.ts

@@ -0,0 +1,261 @@
+import { defineRelations, type SQL } from "drizzle-orm"
+import { PgDialect, text } from "drizzle-orm/pg-core"
+import { drizzle } from "drizzle-orm/postgres-js"
+import { describe, expect, it } from "vitest"
+import {
+  definedValues,
+  excludedSet,
+  functionPermissionTables,
+  maybeOne,
+  one,
+  type QueryExecutor,
+  selectFunctionPermissions,
+} from "./query.ts"
+import { primaryId, schema, table, view } from "./schema.ts"
+
+// No connection anywhere: `drizzle.mock()` builds statements for `.toSQL()`,
+// and `PgDialect` renders a bare `SQL` the way the driver would receive it.
+const db = drizzle.mock()
+const dialect = new PgDialect()
+const render = (query: SQL) => dialect.sqlToQuery(query)
+
+const contacts = table("contacts", {
+  displayName: text(),
+  email: text(),
+  id: primaryId("sequential"),
+})
+
+const dealsProperties = table("deals_properties", {
+  dealId: text().notNull(),
+  propertyId: text().notNull(),
+})
+
+describe("one", () => {
+  it("returns the only row", () => {
+    expect(one([{ id: 1 }])).toEqual({ id: 1 })
+  })
+
+  it("throws on none and on several", () => {
+    expect(() => one([])).toThrow("Expected exactly one row, received 0")
+    expect(() => one([1, 2])).toThrow("Expected exactly one row, received 2")
+  })
+})
+
+describe("maybeOne", () => {
+  it("returns the row, or undefined for none", () => {
+    expect(maybeOne([{ id: 1 }])).toEqual({ id: 1 })
+    expect(maybeOne([])).toBeUndefined()
+  })
+
+  it("throws on several", () => {
+    expect(() => maybeOne([1, 2])).toThrow(
+      "Expected at most one row, received 2"
+    )
+  })
+})
+
+describe("definedValues", () => {
+  it("drops undefined keys and keeps null", () => {
+    expect(definedValues({ a: 1, b: undefined, c: null })).toEqual({
+      a: 1,
+      c: null,
+    })
+  })
+})
+
+describe("excludedSet", () => {
+  const upsert = (values: Record<string, unknown>, set: Record<string, SQL>) =>
+    db
+      .insert(contacts)
+      .values({ id: 1, ...values })
+      .onConflictDoUpdate({ set, target: contacts.id })
+      .toSQL().sql
+
+  it("writes back every supplied column by its database name, never the target", () => {
+    const values = { displayName: "Ada", email: "ada@example.com", id: 1 }
+
+    expect(upsert(values, excludedSet(contacts, values))).toContain(
+      'do update set "display_name" = excluded."display_name", "email" = excluded."email"'
+    )
+  })
+
+  it("skips a key carrying undefined", () => {
+    const values = { displayName: undefined, email: "ada@example.com" }
+    const set = excludedSet(contacts, values)
+
+    expect(Object.keys(set)).toEqual(["email"])
+  })
+
+  it("falls back to id = excluded.id when nothing else is supplied", () => {
+    const set = excludedSet(contacts, { displayName: undefined, id: 1 })
+
+    expect(upsert({}, set)).toContain('do update set "id" = excluded."id"')
+  })
+
+  it("takes another conflict target", () => {
+    const values = { displayName: "Ada", email: "ada@example.com" }
+    const set = excludedSet(contacts, values, { target: "email" })
+
+    expect(Object.keys(set)).toEqual(["displayName"])
+    expect(render(one(Object.values(set))).sql).toBe('excluded."display_name"')
+  })
+
+  it("falls back to the first target column that exists", () => {
+    const set = excludedSet(
+      dealsProperties,
+      { dealId: "d", propertyId: "p" },
+      { target: ["dealId", "propertyId"] }
+    )
+
+    expect(Object.keys(set)).toEqual(["dealId"])
+    expect(render(one(Object.values(set))).sql).toBe('excluded."deal_id"')
+  })
+
+  it("stays empty for a table without the default id target", () => {
+    expect(excludedSet(dealsProperties, {})).toEqual({})
+  })
+})
+
+const billing = schema("billing")
+const invoices = billing.table("invoices", { id: primaryId("sequential") })
+const privateNotes = schema("private").table("notes", {
+  id: primaryId("sequential"),
+})
+const contactNames = view("contact_names").as((qb) =>
+  qb.select({ displayName: contacts.displayName }).from(contacts)
+)
+
+describe("functionPermissionTables", () => {
+  const schemaObject = {
+    billing,
+    contactNames,
+    contacts,
+    invoices,
+    privateNotes,
+    relationsHelper: () => undefined,
+  }
+
+  it("includes only public tables by default", () => {
+    expect([...functionPermissionTables(schemaObject)]).toEqual([
+      ["contacts", "public"],
+    ])
+  })
+
+  it("maps each table to its own schema", () => {
+    expect(
+      new Map(
+        functionPermissionTables(schemaObject, {
+          schemas: ["public", "billing"],
+        })
+      )
+    ).toEqual(
+      new Map([
+        ["contacts", "public"],
+        ["invoices", "billing"],
+      ])
+    )
+  })
+
+  it("accepts the result of defineRelations", () => {
+    const relations = defineRelations({ contacts, invoices })
+
+    expect([
+      ...functionPermissionTables(relations, { schemas: ["billing"] }),
+    ]).toEqual([["invoices", "billing"]])
+  })
+
+  it("rejects a bare name that two included schemas share", () => {
+    const publicInvoices = table("invoices", { id: primaryId("sequential") })
+
+    expect(() =>
+      functionPermissionTables(
+        { invoices, publicInvoices },
+        { schemas: ["public", "billing"] }
+      )
+    ).toThrow('Table "invoices" exists in both')
+  })
+})
+
+describe("selectFunctionPermissions", () => {
+  const tables = functionPermissionTables(
+    { contacts, invoices },
+    { schemas: ["public", "billing"] }
+  )
+
+  // Records the statement and answers with a canned row: no database.
+  const fakeDb = (row: Record<string, boolean | null>) => {
+    const queries: SQL[] = []
+    const executor: QueryExecutor = {
+      execute: (query) => {
+        queries.push(query)
+        return Promise.resolve([row])
+      },
+    }
+    return { executor, queries }
+  }
+
+  it("calls all four functions in one statement, id to all but insert", async () => {
+    const { executor, queries } = fakeDb({
+      delete: false,
+      insert: true,
+      select: true,
+      update: null,
+    })
+
+    const permissions = await selectFunctionPermissions(executor, {
+      id: 7,
+      table: "invoices",
+      tables,
+    })
+
+    expect(permissions).toEqual({
+      delete: false,
+      insert: true,
+      select: true,
+      update: false,
+    })
+    const query = render(one(queries))
+    expect(query.sql).toBe(
+      'select "billing"."can_select_invoices"("id" => $1) as "select", "billing"."can_insert_invoices"() as "insert", "billing"."can_update_invoices"("id" => $2) as "update", "billing"."can_delete_invoices"("id" => $3) as "delete"'
+    )
+    expect(query.params).toEqual([7, 7, 7])
+  })
+
+  it("calls every function bare without an id, honouring prefix and schema", async () => {
+    const { executor, queries } = fakeDb({
+      delete: true,
+      insert: true,
+      select: true,
+      update: true,
+    })
+
+    await selectFunctionPermissions(executor, {
+      functionSchema: "private",
+      prefix: "may",
+      table: "contacts",
+      tables,
+    })
+
+    expect(render(one(queries)).sql).toBe(
+      'select "private"."may_select_contacts"() as "select", "private"."may_insert_contacts"() as "insert", "private"."may_update_contacts"() as "update", "private"."may_delete_contacts"() as "delete"'
+    )
+  })
+
+  it("rejects a table outside the allowlist before building anything", async () => {
+    const { executor, queries } = fakeDb({})
+
+    await expect(
+      selectFunctionPermissions(executor, {
+        table: 'contacts"; drop table contacts; --',
+        tables,
+      })
+    ).rejects.toThrow("No permission functions for table")
+    expect(queries).toHaveLength(0)
+  })
+
+  it("accepts a real Drizzle client", () => {
+    // Compile-time only: the structural type fits a postgres-js database.
+    const executor: QueryExecutor = db
+    expect(executor.execute).toBeTypeOf("function")
+  })
+})

package/src/query.ts

@@ -0,0 +1,252 @@
+// Query-side helpers: the PostgREST conveniences Drizzle has no equivalent for
+// (`.single()`, `.maybeSingle()`, a default upsert `set`), plus the read side
+// of `functionPolicies`.
+import { getColumns, is, type SQL, sql } from "drizzle-orm"
+import { getTableConfig, PgTable } from "drizzle-orm/pg-core"
+import {
+  DEFAULT_FUNCTION_PREFIX,
+  FUNCTION_POLICY_OPERATIONS,
+  type FunctionPolicyOperation,
+  functionPolicyName,
+} from "./function-names.ts"
+
+/**
+ * PostgREST's `.single()`: exactly one row, or an error.
+ *
+ * `findFirst()` returns `undefined` for no rows and silently drops the rest
+ * when there are several, and `.returning()` hands back an array.
+ */
+export const one = <T>(rows: readonly T[]): T => {
+  if (rows.length !== 1) {
+    throw new Error(`Expected exactly one row, received ${rows.length}`)
+  }
+
+  return rows[0] as T
+}
+
+/**
+ * PostgREST's `.maybeSingle()`: one row or none, erroring on more than one.
+ * Returns `undefined` rather than `null`, which is what `findFirst()` does.
+ */
+export const maybeOne = <T>(rows: readonly T[]): T | undefined => {
+  if (rows.length > 1) {
+    throw new Error(`Expected at most one row, received ${rows.length}`)
+  }
+
+  return rows[0]
+}
+
+type ColumnKey<TTable extends PgTable> = Extract<
+  keyof TTable["_"]["columns"],
+  string
+>
+
+export type ExcludedSetOptions<TTable extends PgTable> = {
+  /**
+   * The conflict target's column keys, never written back from `excluded`.
+   * The first one that exists is also the empty-set fallback. Default `"id"`.
+   */
+  target?: ColumnKey<TTable> | readonly ColumnKey<TTable>[]
+}
+
+/**
+ * The `set` for `onConflictDoUpdate` that reproduces PostgREST's
+ * `.upsert(row, { onConflict })`: on conflict, every column the caller
+ * supplied is overwritten from the proposed row (`col = excluded.col`).
+ *
+ * - A key carrying `undefined` is skipped. Drizzle omits an undefined column
+ *   from the INSERT, so `excluded.x` would be the column default, and on a
+ *   conflict `x = excluded.x` would overwrite a stored value with it.
+ * - The conflict target (`id` unless `target` says otherwise) is excluded.
+ * - An empty result falls back to `<target> = excluded.<target>`. Drizzle
+ *   throws `No values to set` while *building* the statement, so a payload
+ *   holding nothing but the key would fail even on the plain insert path.
+ *   Writing the key back to itself is a no-op that keeps `.returning()`
+ *   yielding the row, which `onConflictDoNothing` does not.
+ *
+ * With no target column in the table (a junction keyed only by its foreign
+ * keys, with the default target) the fallback cannot apply and the result
+ * stays empty: such a table wants `onConflictDoNothing` anyway.
+ *
+ * Column names come from the schema, never from `values`.
+ */
+export const excludedSet = <TTable extends PgTable>(
+  table: TTable,
+  values: Record<string, unknown>,
+  { target = "id" as ColumnKey<TTable> }: ExcludedSetOptions<TTable> = {}
+): Record<string, SQL> => {
+  const columns: Record<string, { name: string }> = getColumns(table)
+  const targets: readonly string[] =
+    typeof target === "string" ? [target] : target
+  const set: Record<string, SQL> = {}
+
+  for (const [key, column] of Object.entries(columns)) {
+    if (key in values && values[key] !== undefined && !targets.includes(key)) {
+      set[key] = sql`excluded.${sql.identifier(column.name)}`
+    }
+  }
+
+  if (Object.keys(set).length > 0) {
+    return set
+  }
+
+  const fallback = targets.find((key) => key in columns)
+  const fallbackColumn = fallback === undefined ? undefined : columns[fallback]
+
+  if (fallback !== undefined && fallbackColumn) {
+    set[fallback] = sql`excluded.${sql.identifier(fallbackColumn.name)}`
+  }
+
+  return set
+}
+
+/**
+ * The same values with every `undefined` key dropped, so an insert and its
+ * `excludedSet` agree on which columns were supplied.
+ */
+export const definedValues = <T extends Record<string, unknown>>(
+  values: T
+): T =>
+  Object.fromEntries(
+    Object.entries(values).filter(([, value]) => value !== undefined)
+  ) as T
+
+/** Table name to the schema its `<prefix>_<operation>_<table>` functions live in. */
+export type FunctionPermissionTables = ReadonlyMap<string, string>
+
+export type FunctionPermissionTablesOptions = {
+  /** Schemas whose tables are included. Default `["public"]`. */
+  schemas?: readonly string[]
+}
+
+const DEFAULT_SCHEMA = "public"
+
+// A schema module exports tables directly; `defineRelations` wraps each in
+// `{ table, name, relations }`. Both are accepted so either object works.
+const tableOf = (value: unknown): PgTable | undefined => {
+  if (is(value, PgTable)) {
+    return value
+  }
+  if (typeof value === "object" && value !== null && "table" in value) {
+    const { table } = value
+    return is(table, PgTable) ? table : undefined
+  }
+  return
+}
+
+/**
+ * The allowlist `selectFunctionPermissions` resolves a table name against,
+ * built from a Drizzle schema object (`import * as schema`) or the result of
+ * `defineRelations`. Build it once at module scope. Views and non-table
+ * exports are ignored; a table name that appears in two included schemas
+ * throws, since a bare name could not tell them apart.
+ */
+export const functionPermissionTables = (
+  schemaObject: Record<string, unknown>,
+  { schemas = [DEFAULT_SCHEMA] }: FunctionPermissionTablesOptions = {}
+): FunctionPermissionTables => {
+  const tables = new Map<string, string>()
+
+  for (const value of Object.values(schemaObject)) {
+    const table = tableOf(value)
+    if (!table) {
+      continue
+    }
+    const { name, schema = DEFAULT_SCHEMA } = getTableConfig(table)
+    if (!schemas.includes(schema)) {
+      continue
+    }
+    const existing = tables.get(name)
+    if (existing !== undefined && existing !== schema) {
+      throw new Error(
+        `Table "${name}" exists in both "${existing}" and "${schema}"; include only one of those schemas`
+      )
+    }
+    tables.set(name, schema)
+  }
+
+  return tables
+}
+
+export type FunctionPermissions = Record<FunctionPolicyOperation, boolean>
+
+/**
+ * Anything with Drizzle's `execute` returning rows: a postgres-js client from
+ * `@zeno-lib/db`, a `PgAsyncDatabase`, or a transaction.
+ */
+export type QueryExecutor = {
+  execute: (query: SQL) => PromiseLike<readonly Record<string, unknown>[]>
+}
+
+export type SelectFunctionPermissionsOptions = {
+  /** From `functionPermissionTables`. */
+  tables: FunctionPermissionTables
+  /** The table asked about, checked against `tables`. */
+  table: string
+  /**
+   * The row, passed to every function but `insert` (there is no row yet) as
+   * a named argument. Omit to call all four with none.
+   */
+  id?: number | string
+  /** Name of the functions' row parameter. Default `"id"`. */
+  argumentName?: string
+  /** Function prefix, as given to `functionPolicies`. Default `"can"`. */
+  prefix?: string
+  /** Schema the functions live in. Default: the table's own. */
+  functionSchema?: string
+}
+
+/**
+ * The four `<prefix>_<operation>_<table>()` answers for one table, in one
+ * statement: the read side of `functionPolicies`, for showing or hiding UI.
+ *
+ * `table` is only ever a map key: every identifier that reaches the statement
+ * comes from `tables` and is quoted with `sql.identifier`. A function missing
+ * or with another signature raises `42883` (`SqlState.undefinedFunction`).
+ * A `null` answer, which a function gives for a row the caller cannot see,
+ * counts as `false`, as does anything else that is not `true`.
+ */
+export const selectFunctionPermissions = async (
+  db: QueryExecutor,
+  {
+    argumentName = "id",
+    functionSchema,
+    id,
+    prefix = DEFAULT_FUNCTION_PREFIX,
+    table,
+    tables,
+  }: SelectFunctionPermissionsOptions
+): Promise<FunctionPermissions> => {
+  const tableSchema = tables.get(table)
+
+  if (tableSchema === undefined) {
+    throw new Error(`No permission functions for table "${table}"`)
+  }
+
+  const schema = functionSchema ?? tableSchema
+
+  const call = (operation: FunctionPolicyOperation) => {
+    const callee = sql`${sql.identifier(schema)}.${sql.identifier(functionPolicyName(prefix, operation, table))}`
+    return operation === "insert" || id === undefined
+      ? sql`${callee}()`
+      : sql`${callee}(${sql.identifier(argumentName)} => ${id})`
+  }
+
+  const row = one(
+    await db.execute(
+      sql`select ${sql.join(
+        FUNCTION_POLICY_OPERATIONS.map(
+          (operation) => sql`${call(operation)} as ${sql.identifier(operation)}`
+        ),
+        sql`, `
+      )}`
+    )
+  )
+
+  return {
+    delete: row.delete === true,
+    insert: row.insert === true,
+    select: row.select === true,
+    update: row.update === true,
+  }
+}

package/src/schema.test-d.ts

@@ -7,6 +7,7 @@ import {
   primaryId,
   sequentialPrimaryId,
   table,
+  timestamps,
   userId,
   uuidPrimaryId,
 } from "./schema.ts"
@@ -119,3 +120,26 @@ test("reference actions are rejected when there is no reference", () => {
   // @ts-expect-error actions are meaningless without a foreign key
   authUserId({ actions: { onDelete: "cascade" }, reference: null })
 })
+
+test("timestamps reads a Date by default and a string with mode: string", () => {
+  const dated = table("dated", { ...timestamps() })
+  const stringly = table("stringly", { ...timestamps({ mode: "string" }) })
+  const audited = table("audited_strings", {
+    ...auditColumns({ mode: "string" }),
+  })
+
+  expectTypeOf<
+    (typeof dated)["$inferSelect"]["createdAt"]
+  >().toEqualTypeOf<Date>()
+  expectTypeOf<
+    (typeof stringly)["$inferSelect"]["updatedAt"]
+  >().toEqualTypeOf<string>()
+  expectTypeOf<
+    (typeof audited)["$inferSelect"]["createdAt"]
+  >().toEqualTypeOf<string>()
+  // Both still have a default, so neither is required on insert.
+  expectTypeOf<(typeof stringly)["$inferInsert"]>().toEqualTypeOf<{
+    createdAt?: string | undefined
+    updatedAt?: string | undefined
+  }>()
+})

package/src/schema.ts

@@ -10,6 +10,8 @@ import {
   type PgBigInt64Builder,
   type PgIntegerBuilder,
   type PgPolicyConfig,
+  type PgTimestampBuilder,
+  type PgTimestampStringBuilder,
   type PgUUIDBuilder,
   type Precision,
   pgPolicy,
@@ -24,6 +26,12 @@ import {
 import { snakeCase } from "drizzle-orm/pg-core/casing"
 import { authenticatedRole, authUid } from "drizzle-orm/supabase"
 import { authUsers } from "./auth-schema.ts"
+import {
+  DEFAULT_FUNCTION_PREFIX,
+  FUNCTION_POLICY_OPERATIONS,
+  type FunctionPolicyOperation,
+  functionPolicyName,
+} from "./function-names.ts"
 
 // pg-core primitives without the `pg` prefix they repeat at every call site.
 // `table` is missing on purpose. Zeno's own is at the bottom of this file.
@@ -56,12 +64,34 @@ export {
   supabaseAuthAdminRole,
 } from "drizzle-orm/supabase"
 
-type TimestampsOptions = {
+/** How a timestamp column is read back: a `Date` (the default) or Postgres's own text. */
+export type TimestampMode = "date" | "string"
+
+export type TimestampsOptions<TMode extends TimestampMode = "date"> = {
+  /**
+   * `"date"` (the default) reads a `Date`; `"string"` keeps Postgres's text
+   * form, which also keeps the microseconds a `Date` truncates. A JavaScript
+   * mapping only: it emits no SQL.
+   */
+  mode?: TMode
   withTimezone?: boolean
   /** Fractional-second digits. Postgres allows 0 to 6. */
   precision?: Precision
 }
 
+// Mirrors drizzle's own `timestamp()` overload: only an exact `"string"` gives
+// the string builder.
+type TimestampColumn<TMode extends TimestampMode> = SetHasDefault<
+  SetNotNull<
+    [TMode] extends ["string"] ? PgTimestampStringBuilder : PgTimestampBuilder
+  >
+>
+
+export type TimestampColumns<TMode extends TimestampMode = "date"> = {
+  createdAt: TimestampColumn<TMode>
+  updatedAt: TimestampColumn<TMode>
+}
+
 // `created_at` is a column DEFAULT, so Postgres fills it for every writer.
 // `updated_at` has no equivalent: SQL has no "on update" default, and Drizzle's
 // `$onUpdateFn` is applied while Drizzle builds its own statement, so a write
@@ -74,16 +104,22 @@ type TimestampsOptions = {
 // than a shared object, because Drizzle's builder methods mutate `this` and
 // return it. One builder in two tables would leak `.notNull()`, `.references()`
 // and its name from whichever table customised it first.
-export const timestamps = ({
+export const timestamps = <TMode extends TimestampMode = "date">({
+  mode,
   precision,
   withTimezone = true,
-}: TimestampsOptions = {}) => {
-  const config = { precision, withTimezone }
+}: TimestampsOptions<TMode> = {}): TimestampColumns<TMode> => {
+  const column = (name: string) =>
+    mode === "string"
+      ? timestamp(name, { mode: "string", precision, withTimezone })
+          .notNull()
+          .defaultNow()
+      : timestamp(name, { precision, withTimezone }).notNull().defaultNow()
 
   return {
-    createdAt: timestamp("created_at", config).notNull().defaultNow(),
-    updatedAt: timestamp("updated_at", config).notNull().defaultNow(),
-  }
+    createdAt: column("created_at"),
+    updatedAt: column("updated_at"),
+  } as TimestampColumns<TMode>
 }
 
 type ReferenceActions = ReferenceConfig["config"]
@@ -208,10 +244,13 @@ export const authorship = <TNotNull extends boolean = false>(
 })
 
 // Takes both halves' options, since it builds both halves.
-export const auditColumns = <TNotNull extends boolean = false>(
-  options: AuthorshipOptions<TNotNull> & TimestampsOptions = {}
+export const auditColumns = <
+  TNotNull extends boolean = false,
+  TMode extends TimestampMode = "date",
+>(
+  options: AuthorshipOptions<TNotNull> & TimestampsOptions<TMode> = {}
 ) => ({
-  ...timestamps(options),
+  ...timestamps<TMode>(options),
   ...authorship<TNotNull>(options),
 })
 
@@ -414,15 +453,6 @@ const POLICY_BUILDERS = {
   update: updatePolicy,
 } as const satisfies Record<PolicyOperation, typeof selectPolicy>
 
-const FUNCTION_POLICY_OPERATIONS = [
-  "select",
-  "insert",
-  "update",
-  "delete",
-] as const
-
-type FunctionPolicyOperation = (typeof FUNCTION_POLICY_OPERATIONS)[number]
-
 /** Columns one function is called with. `null` calls it with none. */
 type FunctionArgument = AnyPgColumn | readonly AnyPgColumn[] | null
 
@@ -515,7 +545,7 @@ export const functionPolicies = (
   {
     argument,
     name,
-    prefix = "can",
+    prefix = DEFAULT_FUNCTION_PREFIX,
     schema: functionSchema,
   }: FunctionPoliciesOptions = {}
 ) => {
@@ -528,7 +558,7 @@ export const functionPolicies = (
   const tableName = getTableName(getColumnTable(firstColumn))
 
   return FUNCTION_POLICY_OPERATIONS.map((operation) => {
-    const functionName = `${prefix}_${operation}_${tableName}`
+    const functionName = functionPolicyName(prefix, operation, tableName)
     // Unqualified by default, so the name resolves through `search_path` the
     // way a hand-written policy would; `schema` pins it to the functions that
     // live beside their table instead.