bisonbase 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,29 @@
+export {
+  ApiError,
+  BisonBase,
+  LiveQuery,
+  NotSignedInError,
+  SchemaError,
+  Table,
+  UserDb,
+  type AuthState,
+  type BisonBaseOptions,
+  type QueryResult,
+  type QueryState,
+  type InsertOf,
+  type RowOf,
+} from './client.ts'
+export type {
+  ColumnSpec,
+  ColumnType,
+  Columns,
+  InsertFor,
+  Json,
+  Ops,
+  OrderBy,
+  RowFor,
+  SelectOptions,
+  UpdateFor,
+  Where,
+  Wire,
+} from './types.ts'

package/src/react.tsx

@@ -0,0 +1,56 @@
+// React bindings. Importing this module makes `table.useSelect()` work.
+
+import { useSyncExternalStore } from 'react'
+import { BisonBase, setHooks, type AuthState, type LiveQuery, type QueryState } from './client.ts'
+
+setHooks({
+  useQuery<R>(query: LiveQuery<R>): QueryState<R> {
+    return useSyncExternalStore(query.subscribe, query.getSnapshot, query.getSnapshot)
+  },
+})
+
+function instance(bb?: BisonBase): BisonBase {
+  const found = bb ?? BisonBase.instance
+  if (!found) throw new Error('Create a BisonBase before rendering components that use it')
+  return found
+}
+
+/** Whether the user is signed in; re-renders when that changes. */
+export function useAuth(bb?: BisonBase): AuthState {
+  const b = instance(bb)
+  return useSyncExternalStore(
+    (listener) => b.onAuthChange(listener),
+    () => b.auth,
+    () => b.auth,
+  )
+}
+
+export interface AuthElementProps {
+  /** Default: the BisonBase created last. */
+  bb?: BisonBase
+  className?: string
+}
+
+/** A sign-in button, or a sign-out button once signed in. Unstyled; target `.bb-auth`. */
+export function AuthElement({ bb, className }: AuthElementProps) {
+  const b = instance(bb)
+  const auth = useAuth(b)
+  const cls = className ? `bb-auth ${className}` : 'bb-auth'
+  if (auth.status === 'pending') return <span className={cls} data-status="pending">Signing in…</span>
+  if (auth.status === 'signed-in') {
+    return (
+      <span className={cls} data-status="signed-in">
+        <span className="bb-auth-label">Signed in</span>{' '}
+        <button type="button" onClick={() => void b.signOut()}>Sign out</button>
+      </span>
+    )
+  }
+  return (
+    <span className={cls} data-status="signed-out">
+      <button type="button" onClick={() => void b.signIn()}>Sign in</button>
+      {auth.error && <span className="bb-auth-error" role="alert"> {auth.error}</span>}
+    </span>
+  )
+}
+
+export { BisonBase }

package/src/schema.ts

@@ -0,0 +1,67 @@
+// Bringing a per-user database in line with the tables the app declares: create missing
+// tables, add new columns, and refuse anything that would change or drop existing data.
+
+import { addColumnSql, createTableSql, SQL_TYPES } from './sql.ts'
+import type { TableDef } from './table.ts'
+
+/** What `GET ?op=schema` returns. */
+export interface ServerSchema {
+  tables: {
+    name: string
+    type: string
+    columns: { name: string; type: string; not_null: boolean; default: unknown; pk: boolean }[]
+  }[]
+}
+
+/** The database's tables don't match the app's and can't be changed to match safely. */
+export class SchemaError extends Error {
+  override name = 'SchemaError'
+}
+
+/** The statements that bring `server` in line with `tables`. Throws SchemaError if that's unsafe. */
+export function migrationSql(tables: Iterable<TableDef>, server: ServerSchema, db: string): string[] {
+  const existing = new Map(server.tables.map((t) => [t.name.toLowerCase(), t]))
+  const statements: string[] = []
+  const fail = (table: string, msg: string) => {
+    throw new SchemaError(`Table "${table}" in ${db}: ${msg}`)
+  }
+  for (const table of tables) {
+    const found = existing.get(table.name.toLowerCase())
+    if (!found) {
+      statements.push(createTableSql(table))
+      continue
+    }
+    if (found.type !== 'table') fail(table.name, `the database has a ${found.type} with this name`)
+    const cols = new Map(found.columns.map((c) => [c.name.toLowerCase(), c]))
+    const id = cols.get('id')
+    if (!id || !id.pk || id.type.toUpperCase() !== 'INTEGER') {
+      fail(table.name, 'it exists but has no "id INTEGER PRIMARY KEY" column, so it wasn\'t created by this library')
+    }
+    if (found.columns.filter((c) => c.pk).length > 1) fail(table.name, 'it has a composite primary key')
+    for (const col of table.columns) {
+      const have = cols.get(col.name.toLowerCase())
+      const want = SQL_TYPES[col.type]
+      if (!have) {
+        if (!col.nullable && !col.default) {
+          fail(table.name, `new column "${col.name}" needs a default (or make it nullable) so existing rows get a value`)
+        }
+        statements.push(addColumnSql(table, col))
+        continue
+      }
+      if (have.type.toUpperCase() !== want) {
+        fail(table.name, `column "${col.name}" is ${have.type || 'untyped'} in the database but declared as ${col.type}; changing a column's type isn't supported`)
+      }
+      if (have.not_null === col.nullable) {
+        const [was, now] = have.not_null ? ['NOT NULL', 'nullable'] : ['nullable', 'not nullable']
+        fail(table.name, `column "${col.name}" is ${was} in the database but declared ${now}; changing that isn't supported`)
+      }
+    }
+    for (const have of found.columns) {
+      const name = have.name.toLowerCase()
+      if (name !== 'id' && !table.columns.some((c) => c.name.toLowerCase() === name)) {
+        fail(table.name, `column "${have.name}" is in the database but not declared; removing columns isn't supported because it would lose data. Declare it again`)
+      }
+    }
+  }
+  return statements
+}

package/src/sql.ts

@@ -0,0 +1,204 @@
+// Compiles structured operations (select / insert / update / delete) to SQL with quoted
+// identifiers and bound parameters. Nothing outside this file and schema.ts writes SQL, so
+// these operations can later move to a server-side relational API without changing callers.
+
+import { encode } from './values.ts'
+import type { ColumnDef, TableDef } from './table.ts'
+import type { ColumnType, Wire } from './types.ts'
+
+export interface Statement {
+  sql: string
+  params: Wire[]
+}
+
+export const quote = (name: string) => `"${name.replaceAll('"', '""')}"`
+
+export const SQL_TYPES: Record<ColumnType, string> = {
+  text: 'TEXT',
+  integer: 'INTEGER',
+  real: 'REAL',
+  boolean: 'BOOLEAN',
+  blob: 'BLOB',
+  json: 'JSON',
+}
+
+const ID: ColumnDef = { name: 'id', type: 'integer', nullable: false }
+
+function column(table: TableDef, name: string): ColumnDef {
+  if (name === 'id') return ID
+  const col = table.byName.get(name)
+  if (!col) throw new Error(`Table "${table.name}" has no column "${name}"`)
+  return col
+}
+
+/** A default value as an SQL literal (DEFAULT clauses can't take parameters). */
+export function literal(col: ColumnDef, value: unknown): string {
+  const wire = encode(col.type, col.nullable, value, col.name)
+  if (wire === null) return 'NULL'
+  if (typeof wire === 'number') return String(wire)
+  if (typeof wire === 'string') return `'${wire.replaceAll("'", "''")}'`
+  const hex = Array.from(atob(wire.$base64), (c) => c.charCodeAt(0).toString(16).padStart(2, '0')).join('')
+  return `X'${hex}'`
+}
+
+/** A column definition for CREATE TABLE or ALTER TABLE ADD COLUMN. */
+export function columnSql(col: ColumnDef): string {
+  let sql = `${quote(col.name)} ${SQL_TYPES[col.type]}`
+  if (!col.nullable) sql += ' NOT NULL'
+  if (col.default) sql += ` DEFAULT ${literal(col, col.default.value)}`
+  return sql
+}
+
+export function createTableSql(table: TableDef): string {
+  const cols = [`"id" INTEGER PRIMARY KEY`, ...table.columns.map(columnSql)]
+  return `CREATE TABLE IF NOT EXISTS ${quote(table.name)} (${cols.join(', ')})`
+}
+
+export function addColumnSql(table: TableDef, col: ColumnDef): string {
+  return `ALTER TABLE ${quote(table.name)} ADD COLUMN ${columnSql(col)}`
+}
+
+const allColumns = (table: TableDef) => ['id', ...table.columns.map((c) => c.name)].map(quote).join(', ')
+
+const OPS: Record<string, string> = { $ne: '<>', $lt: '<', $lte: '<=', $gt: '>', $gte: '>=' }
+
+function isOps(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || value instanceof Uint8Array || Array.isArray(value)) return false
+  const keys = Object.keys(value)
+  return keys.length > 0 && keys.every((k) => k.startsWith('$'))
+}
+
+/** A WHERE clause (including the keyword, or empty) and its parameters. */
+export function whereSql(table: TableDef, where: object | number | undefined, params: Wire[]): string {
+  if (where === undefined) return ''
+  if (typeof where === 'number') where = { id: where }
+  const terms: string[] = []
+  for (const [name, cond] of Object.entries(where)) {
+    const col = column(table, name)
+    const q = quote(name)
+    if (cond === undefined) throw new Error(`where.${name} is undefined; leave it out or use null`)
+    if (!isOps(cond)) {
+      if (cond === null) terms.push(`${q} IS NULL`)
+      else {
+        terms.push(`${q} = ?`)
+        params.push(encode(col.type, col.nullable, cond, name))
+      }
+      continue
+    }
+    for (const [op, value] of Object.entries(cond)) {
+      if (value === undefined) continue
+      if (op === '$in') {
+        if (!Array.isArray(value)) throw new Error(`where.${name}.$in must be an array`)
+        if (value.length === 0) {
+          terms.push('0')
+          continue
+        }
+        terms.push(`${q} IN (${value.map(() => '?').join(', ')})`)
+        for (const v of value) params.push(encode(col.type, col.nullable, v, name))
+      } else if (op === '$ne' && value === null) {
+        terms.push(`${q} IS NOT NULL`)
+      } else if (op === '$ne') {
+        // Like JavaScript's !==, NULL counts as different from any value.
+        terms.push(`${q} IS NOT ?`)
+        params.push(encode(col.type, col.nullable, value, name))
+      } else if (OPS[op]) {
+        terms.push(`${q} ${OPS[op]} ?`)
+        params.push(encode(col.type, col.nullable, value, name))
+      } else {
+        throw new Error(`Unknown operator where.${name}.${op}`)
+      }
+    }
+  }
+  return terms.length ? ` WHERE ${terms.join(' AND ')}` : ''
+}
+
+function orderSql(table: TableDef, orderBy: string | readonly string[] | undefined): string {
+  if (orderBy === undefined) return ''
+  const items = typeof orderBy === 'string' ? [orderBy] : orderBy
+  if (items.length === 0) return ''
+  const parts = items.map((item) => {
+    const [name, dir = 'asc', ...rest] = item.trim().split(/\s+/)
+    const d = dir.toLowerCase()
+    if (rest.length || (d !== 'asc' && d !== 'desc')) throw new Error(`Bad orderBy "${item}"; use "column" or "column desc"`)
+    column(table, name)
+    return `${quote(name)} ${d.toUpperCase()}`
+  })
+  return ` ORDER BY ${parts.join(', ')}`
+}
+
+function count(name: string, n: number | undefined): n is number {
+  if (n === undefined) return false
+  if (!Number.isSafeInteger(n) || n < 0) throw new Error(`${name} must be a non-negative integer`)
+  return true
+}
+
+export interface SelectSpec {
+  where?: object | number
+  orderBy?: string | readonly string[]
+  limit?: number
+  offset?: number
+}
+
+export function selectSql(table: TableDef, opts: SelectSpec = {}): Statement {
+  const params: Wire[] = []
+  let sql = `SELECT ${allColumns(table)} FROM ${quote(table.name)}`
+  sql += whereSql(table, opts.where, params)
+  sql += orderSql(table, opts.orderBy)
+  const hasLimit = count('limit', opts.limit)
+  const hasOffset = count('offset', opts.offset)
+  if (hasLimit || hasOffset) {
+    sql += ' LIMIT ?'
+    params.push(hasLimit ? opts.limit! : -1)
+  }
+  if (hasOffset) {
+    sql += ' OFFSET ?'
+    params.push(opts.offset!)
+  }
+  return { sql, params }
+}
+
+/** INSERT one row, filling in defaults here so the code's defaults win over the database's. */
+export function insertSql(table: TableDef, row: Record<string, unknown>): Statement {
+  for (const name of Object.keys(row)) column(table, name)
+  const names: string[] = []
+  const params: Wire[] = []
+  if (row.id !== undefined) {
+    names.push('id')
+    params.push(encode('integer', false, row.id, 'id'))
+  }
+  for (const col of table.columns) {
+    let value = row[col.name]
+    if (value === undefined) {
+      if (col.default) value = col.default.value
+      else if (col.nullable) value = null
+      else throw new Error(`Missing value for column "${col.name}" of table "${table.name}"`)
+    }
+    names.push(col.name)
+    params.push(encode(col.type, col.nullable, value, col.name))
+  }
+  const sql = names.length
+    ? `INSERT INTO ${quote(table.name)} (${names.map(quote).join(', ')}) VALUES (${names.map(() => '?').join(', ')})`
+    : `INSERT INTO ${quote(table.name)} DEFAULT VALUES`
+  return { sql: `${sql} RETURNING ${allColumns(table)}`, params }
+}
+
+/** UPDATE matching rows, or null when there's nothing to set. */
+export function updateSql(table: TableDef, where: object | number, changes: Record<string, unknown>): Statement | null {
+  const params: Wire[] = []
+  const sets: string[] = []
+  for (const [name, value] of Object.entries(changes)) {
+    if (value === undefined) continue
+    if (name === 'id') throw new Error("A row's id can't be changed")
+    const col = column(table, name)
+    sets.push(`${quote(name)} = ?`)
+    params.push(encode(col.type, col.nullable, value, name))
+  }
+  if (sets.length === 0) return null
+  const sql = `UPDATE ${quote(table.name)} SET ${sets.join(', ')}${whereSql(table, where, params)}`
+  return { sql, params }
+}
+
+export function deleteSql(table: TableDef, where: object | number): Statement {
+  const params: Wire[] = []
+  return { sql: `DELETE FROM ${quote(table.name)}${whereSql(table, where, params)}`, params }
+}

package/src/table.ts

@@ -0,0 +1,48 @@
+// A table's columns, normalized from the spec passed to createTable.
+
+import type { ColumnSpec, ColumnType, Columns } from './types.ts'
+
+export interface ColumnDef {
+  name: string
+  type: ColumnType
+  nullable: boolean
+  /** Present when the column has a default. */
+  default?: { value: unknown }
+}
+
+export interface TableDef {
+  name: string
+  /** Every column except `id`, in declaration order. */
+  columns: ColumnDef[]
+  byName: Map<string, ColumnDef>
+}
+
+const TYPES: readonly ColumnType[] = ['text', 'integer', 'real', 'boolean', 'blob', 'json']
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** Check that a table or column name is a plain identifier. */
+export function checkName(kind: string, name: string): void {
+  if (!IDENT.test(name)) {
+    throw new Error(`${kind} name "${name}" must be letters, digits and underscores, not starting with a digit`)
+  }
+  if (name.toLowerCase().startsWith('sqlite_')) throw new Error(`${kind} name "${name}" is reserved by SQLite`)
+}
+
+function parseColumn(name: string, spec: ColumnSpec): ColumnDef {
+  checkName('Column', name)
+  if (name.toLowerCase() === 'id') throw new Error('Every table gets an "id" column automatically; don\'t declare one')
+  const [base, hasDefault, value] = Array.isArray(spec) ? [spec[0], true, spec[1]] : [spec as string, false, undefined]
+  const nullable = base.endsWith('?')
+  const type = (nullable ? base.slice(0, -1) : base) as ColumnType
+  if (!TYPES.includes(type)) {
+    throw new Error(`Column "${name}" has unknown type "${base}"; use one of ${TYPES.join(', ')}`)
+  }
+  return { name, type, nullable, ...(hasDefault ? { default: { value } } : {}) }
+}
+
+export function parseTable(name: string, columns: Columns): TableDef {
+  checkName('Table', name)
+  const defs = Object.entries(columns).map(([col, spec]) => parseColumn(col, spec))
+  const byName = new Map(defs.map((c) => [c.name, c]))
+  return { name, columns: defs, byName }
+}

package/src/types.ts

@@ -0,0 +1,87 @@
+// Column specs and the row types inferred from them.
+
+/** The column types a table can declare. */
+export type ColumnType = 'text' | 'integer' | 'real' | 'boolean' | 'blob' | 'json'
+
+/** Any value that survives JSON.stringify / JSON.parse. */
+export type Json = string | number | boolean | null | readonly Json[] | { readonly [key: string]: Json }
+
+interface TypeMap {
+  text: string
+  integer: number
+  real: number
+  boolean: boolean
+  blob: Uint8Array
+  json: Json
+}
+
+/** `"text"`, or `"text?"` for a nullable column. */
+type BaseSpec = ColumnType | `${ColumnType}?`
+
+type ValueOfBase<B> = B extends `${infer T extends ColumnType}?`
+  ? TypeMap[T] | null
+  : B extends ColumnType
+    ? TypeMap[B]
+    : never
+
+/** `[type, default]`: the default must have the column's type. */
+type WithDefault<B> = B extends BaseSpec ? readonly [B, ValueOfBase<B>] : never
+
+/**
+ * A column: `"text"`, `"text?"` (nullable), or `["boolean", false]` (with a default).
+ * Nullable columns and columns with a default are optional on insert.
+ */
+export type ColumnSpec = BaseSpec | WithDefault<BaseSpec>
+
+/** The columns passed to `createTable`. `id` is added automatically. */
+export type Columns = { readonly [name: string]: ColumnSpec }
+
+type BaseOf<S> = S extends readonly [infer B, unknown] ? B : S
+
+/** The TypeScript type of a column's values. */
+export type ValueOf<S> = ValueOfBase<BaseOf<S>>
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+type OptionalKeys<C> = {
+  [K in keyof C]: C[K] extends readonly unknown[] ? K : C[K] extends `${string}?` ? K : never
+}[keyof C]
+
+/** A row as read from a table with these columns. */
+export type RowFor<C> = Simplify<{ id: number } & { -readonly [K in keyof C]: ValueOf<C[K]> }>
+
+/** What `insert` takes: nullable columns and columns with a default may be left out. */
+export type InsertFor<C> = Simplify<
+  { id?: number } & { -readonly [K in Exclude<keyof C, OptionalKeys<C>>]: ValueOf<C[K]> } & {
+    -readonly [K in OptionalKeys<C>]?: ValueOf<C[K]>
+  }
+>
+
+/** What `update` takes: any subset of the columns. */
+export type UpdateFor<C> = Simplify<{ -readonly [K in keyof C]?: ValueOf<C[K]> }>
+
+/** Comparisons other than equality, e.g. `{ start: { $gte: from, $lt: to } }`. */
+export interface Ops<T> {
+  $ne?: T
+  $lt?: T
+  $lte?: T
+  $gt?: T
+  $gte?: T
+  $in?: readonly T[]
+}
+
+/** Rows match when every listed column matches. `null` matches NULL. */
+export type Where<R> = { [K in keyof R]?: R[K] | Ops<R[K]> }
+
+/** A column name, optionally followed by `" asc"` or `" desc"`. */
+export type OrderBy<R> = (keyof R & string) | `${keyof R & string} ${'asc' | 'desc'}`
+
+export interface SelectOptions<R> {
+  where?: Where<R>
+  orderBy?: OrderBy<R> | readonly OrderBy<R>[]
+  limit?: number
+  offset?: number
+}
+
+/** A value as sent to or returned by the bisonbase API. */
+export type Wire = string | number | null | { $base64: string }

package/src/values.ts

@@ -0,0 +1,99 @@
+// Converting values between their TypeScript form and what the API sends over the wire:
+// booleans are stored as 0/1, blobs travel as {"$base64": ...}, json is stored as text.
+
+import type { ColumnType, Wire } from './types.ts'
+
+export function toBase64(bytes: Uint8Array): string {
+  let s = ''
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    s += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  }
+  return btoa(s)
+}
+
+export function fromBase64(b64: string): Uint8Array {
+  const s = atob(b64)
+  const bytes = new Uint8Array(s.length)
+  for (let i = 0; i < s.length; i++) bytes[i] = s.charCodeAt(i)
+  return bytes
+}
+
+/** Describe a value for an error message. */
+function describe(value: unknown): string {
+  if (value === null) return 'null'
+  if (value instanceof Uint8Array) return 'Uint8Array'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
+
+const EXPECTED: Record<ColumnType, string> = {
+  text: 'a string',
+  integer: 'an integer',
+  real: 'a finite number',
+  boolean: 'a boolean',
+  blob: 'a Uint8Array',
+  json: 'a JSON value',
+}
+
+/** Convert a column value to its wire form, checking its type. `column` names it in errors. */
+export function encode(type: ColumnType, nullable: boolean, value: unknown, column: string): Wire {
+  const bad = () =>
+    new TypeError(`Column "${column}" expects ${EXPECTED[type]}${nullable ? ' or null' : ''}, got ${describe(value)}`)
+  if (value === undefined) throw bad()
+  if (value === null) {
+    if (nullable) return null
+    if (type === 'json') return 'null'
+    throw bad()
+  }
+  switch (type) {
+    case 'text':
+      if (typeof value !== 'string') throw bad()
+      return value
+    case 'integer':
+      if (typeof value !== 'number' || !Number.isSafeInteger(value)) throw bad()
+      return value
+    case 'real':
+      if (typeof value !== 'number' || !Number.isFinite(value)) throw bad()
+      return value
+    case 'boolean':
+      if (typeof value !== 'boolean') throw bad()
+      return value ? 1 : 0
+    case 'blob':
+      if (!(value instanceof Uint8Array)) throw bad()
+      return { $base64: toBase64(value) }
+    case 'json': {
+      const text = JSON.stringify(value)
+      if (text === undefined) throw bad()
+      return text
+    }
+  }
+}
+
+/** Convert a wire value read from a column back to its TypeScript form. */
+export function decode(type: ColumnType, value: Wire): unknown {
+  if (value === null) return null
+  switch (type) {
+    case 'boolean':
+      return value !== 0 && value !== '0' && value !== ''
+    case 'blob':
+      return typeof value === 'object' ? fromBase64(value.$base64) : new TextEncoder().encode(String(value))
+    case 'json':
+      // SQLite may have stored numeric JSON as a number (the column has numeric affinity).
+      return typeof value === 'string' ? JSON.parse(value) : value
+    default:
+      return value
+  }
+}
+
+/** Convert a value used in raw SQL (`db.sql`) to its wire form. */
+export function encodeParam(value: unknown): Wire {
+  if (value === null || typeof value === 'string') return value
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError(`SQL parameter must be finite, got ${value}`)
+    return value
+  }
+  if (typeof value === 'boolean') return value ? 1 : 0
+  if (value instanceof Uint8Array) return { $base64: toBase64(value) }
+  if (value === undefined) throw new TypeError('SQL parameter is undefined')
+  return JSON.stringify(value)
+}