@zeno-lib/db 0.3.2 → 0.4.0

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.