@juit/pgproxy-persister 1.0.0

package/src/model.ts

@@ -0,0 +1,462 @@
+import type { PGQueryable } from '@juit/pgproxy-client'
+
+/* ========================================================================== *
+ * SIMPLE ASSERTIONS                                                          *
+ * ========================================================================== */
+
+function assert(assertion: any, message: string): asserts assertion {
+  if (! assertion) throw new Error(message)
+}
+
+function assertArray(value: any, message: string): asserts value is any[] {
+  assert(Array.isArray(value), message)
+}
+
+function assertObject(value: any, message: string): asserts value is object {
+  assert(value && (typeof value === 'object'), message)
+}
+
+/* ========================================================================== *
+ * TYPE INFERENCE: FROM SCHEMA->TABLE->COLUMN->... TO JS TYPES                *
+ * ========================================================================== */
+
+type SimplifyIntersection<T> = { [ K in keyof T ]: T[K] }
+type OnlyStrings<T> = T extends string ? T : never
+
+/** The definition of a column */
+export interface ColumnDefinition<T = any> {
+  /** The TypeScript type of the column (from the type parser) */
+  type: T,
+  /** Whether the column is _nulable_ or not */
+  isNullable?: boolean,
+  /** Whether the column _specifies a default value_ or not */
+  hasDefault?: boolean,
+}
+
+/** Infer the TypeScript type suitable for an `INSERT` in a table */
+export type InferInsertType<Table extends Record<string, ColumnDefinition>> =
+  SimplifyIntersection<{
+    /* First part: all nullable or defaulted columns are optional */
+    [ Column in keyof Table as
+      Column extends string ?
+        Table[Column]['isNullable'] extends true ? Column :
+        Table[Column]['hasDefault'] extends true ? Column :
+        never :
+      never
+    ] ? :
+      Table[Column]['isNullable'] extends true ?
+        Table[Column]['type'] | null :
+        Table[Column]['type']
+  } & {
+    /* Second part: all non-nullable or non-defaulted columns are required */
+    [ Column in keyof Table as
+      Column extends string ?
+        Table[Column]['isNullable'] extends true ? never :
+        Table[Column]['hasDefault'] extends true ? never :
+        Column :
+      never
+    ] -? :
+      Table[Column]['isNullable'] extends true ?
+        Table[Column]['type'] | null :
+        Table[Column]['type']
+  }>
+
+/** Infer the TypeScript type suitable for a `SELECT` from a table */
+export type InferSelectType<Table extends Record<string, ColumnDefinition>> =
+  { [ Column in keyof Table as
+      Column extends string ? Column : never
+    ] -? :
+      Table[Column]['isNullable'] extends true ?
+        Table[Column]['type'] | null :
+        Table[Column]['type']
+  }
+
+/** Infer the TypeScript type suitable for a `UPDATE` in a table */
+export type InferUpdateType<Table extends Record<string, ColumnDefinition>> =
+  { [ Column in keyof Table as
+      Column extends string ? Column : never
+    ] ? :
+      Table[Column]['isNullable'] extends true ?
+        Table[Column]['type'] | null :
+        Table[Column]['type']
+  }
+
+/** Infer the available sort values for a table (as required by `ORDER BY`) */
+export type InferSort<Table extends Record<string, ColumnDefinition>> =
+  `${OnlyStrings<keyof Table>}${' ASC' | ' asc' | ' DESC' | ' desc' | ''}`
+
+/* ========================================================================== *
+ * MODEL INTERFACE                                                            *
+ * ========================================================================== */
+
+/** The model interface defines a CRUD interface to PosgreSQL tables */
+export interface Model<Table extends Record<string, ColumnDefinition>> {
+  /**
+   * Create a row in the table.
+   *
+   * @param data - The data to insert in the table
+   * @returns A record containing all colums from the table (including defaults)
+   */
+  create(
+    data: InferInsertType<Table>,
+  ): Promise<InferSelectType<Table>>
+
+  /**
+   * Insert a row in the database or update its contents on conflict.
+   *
+   * @param keys - The data uniquely identifying the row to upsert (primary key)
+   * @param data - The data to associate with the given key (all extra columns)
+   * @returns A record containing all colums from the table (including defaults)
+   */
+  upsert<K extends InferUpdateType<Table>>(
+    keys: K,
+    data: Omit<InferInsertType<Table>, keyof K>,
+  ): Promise<InferSelectType<Table>>
+
+  /**
+   * Read all rows in the table associated with the specified query
+   *
+   * @param query - The columns whose values need to be queried (for equality)
+   * @param sort - Any sort criteria to order the data
+   * @param offset - The offset of the results to return
+   * @param length - The maximum number of rows to return
+   * @returns An array of records containing all columns from the table
+   */
+  read(
+    query?: InferUpdateType<Table>,
+    sort?: InferSort<Table> | InferSort<Table>[],
+    offset?: number,
+    limit?: number,
+  ): Promise<InferSelectType<Table>[]>
+
+  /**
+   * Find the _first_ rows in the table associated with the specified query
+   *
+   * @param query - The columns whose values need to be queried (for equality)
+   * @param sort - Any sort criteria to order the data
+   * @returns The first records matching the query or `undefined`
+   */
+  find(
+    query?: InferUpdateType<Table>,
+    sort?: InferSort<Table> | InferSort<Table>[],
+  ): Promise<InferSelectType<Table> | undefined>
+
+  /**
+   * Update all rows in the table matching the specified query.
+   *
+   * This method _will fail_ when query is the empty object `{}` as we cowardly
+   * refuse to update all records in a table (by design).
+   *
+   * @param query - The columns whose values need to be queried (for equality)
+   * @param patch - The updated data to persist in the table
+   * @returns An array of updated records containing all columns from the table
+   */
+  update(
+    query: InferUpdateType<Table>,
+    patch: InferUpdateType<Table>,
+  ): Promise<InferSelectType<Table>[]>
+
+  /**
+   * Delete all rows in the table matching the specified query.
+   *
+   * This method _will fail_ when query is the empty object `{}` as we cowardly
+   * refuse to delete all records in a table (by design).
+   *
+   * @param query - The columns whose values need to be queried (for equality)
+   * @returns The number of rows deleted
+   */
+  delete(
+    query: InferUpdateType<Table>,
+  ): Promise<number>
+}
+
+/** Constructor for model instances */
+export interface ModelConstructor {
+  new <Schema extends Record<string, ColumnDefinition>>(
+    queryable: PGQueryable,
+    table: string,
+  ): Model<Schema>
+}
+
+/* ========================================================================== *
+ * IMPLEMENTATION                                                             *
+ * ========================================================================== */
+
+/** The tuple `[ SQL, parameters ]` for `query(...)` */
+type Query = [ sql: string, params: any[] ]
+
+/** Prepare a `WHERE` partial statement */
+function where(
+    query: Record<string, any>,
+    params: any[],
+) : [ ...Query, count: number ] {
+  const conditions = []
+
+  let count = 0
+  for (const [ column, value ] of Object.entries(query)) {
+    if (value === undefined) continue
+    if (value === null) {
+      conditions.push(`${escape(column)} IS NULL`)
+    } else {
+      const index = params.push(value)
+      conditions.push(`${escape(column)}=$${index}`)
+    }
+    count ++
+  }
+
+  return [
+    conditions.length ? ` WHERE ${conditions.join(' AND ')}` : '',
+    params,
+    count,
+  ]
+}
+
+/** Prepare an `INSERT` statement for a table */
+function insert(
+    schema: string,
+    table: string,
+    query: Record<string, any>,
+): Query {
+  assertObject(query, 'Called INSERT with a non-object')
+
+  const columns = []
+  const placeholders = []
+  const values = []
+
+  for (const [ column, value ] of Object.entries(query)) {
+    if (value === undefined) continue
+    const index = columns.push(`${escape(column)}`)
+    placeholders.push(`$${index}`)
+    values.push(value)
+  }
+
+  return [
+    columns.length == 0 ?
+      `INSERT INTO ${escape(schema)}.${escape(table)} DEFAULT VALUES RETURNING *` :
+      `INSERT INTO ${escape(schema)}.${escape(table)} (${columns.join()}) VALUES (${placeholders.join()}) RETURNING *`,
+    values,
+  ]
+}
+
+/** Prepare an _upsert_ (`INSERT ... ON CONFLICT`) statement for a table */
+function upsert(
+    schema: string,
+    table: string,
+    keys: Record<string, any>,
+    data: Record<string, any>,
+): Query {
+  assertObject(keys, 'Called UPSERT with a non-object for keys')
+  assertObject(data, 'Called UPSERT with a non-object for data')
+
+  assert(Object.keys(keys).length > 0, 'Called UPSERT with no conflict keys')
+  assert(Object.keys(data).length > 0, 'Called UPSERT with no updateable data')
+
+  /* Keys twice, they go first and override! */
+  const object: Record<string, any> = { ...keys, ...data, ...keys }
+
+  /* For "insert" */
+  const columns: string[] = []
+  const placeholders: string[] = []
+  const values: any[] = []
+  for (const [ column, value ] of Object.entries(object)) {
+    if (value === undefined) continue
+    const index = columns.push(`${escape(column)}`)
+    placeholders.push(`$${index}`)
+    values.push(value)
+  }
+
+  /* For "on conflict" */
+  const conflictKeys: string[] = []
+  for (const [ column, value ] of Object.entries(keys)) {
+    if (value !== undefined) conflictKeys.push(escape(column))
+  }
+
+  /* For "update" */
+  const updates: string[] = []
+  for (const [ column, value ] of Object.entries(data)) {
+    if (value === undefined) continue
+    updates.push(`${escape(column)}=$${updates.length + columns.length + 1}`)
+    values.push(value)
+  }
+
+  /* Our "upsert" statement */
+  return [
+    `INSERT INTO ${escape(schema)}.${escape(table)} (${columns.join()}) VALUES (${placeholders.join()}) ` +
+    `ON CONFLICT (${conflictKeys.join(',')}) ` +
+    `DO UPDATE SET ${updates.join(',')} RETURNING *`,
+    values,
+  ]
+}
+
+/** Prepare a `SELECT` statement for a table */
+function select(
+    schema: string,
+    table: string,
+    query: Record<string, any>,
+    sort: string | string[],
+    offset: number,
+    limit: number,
+): Query {
+  if (typeof sort === 'string') sort = [ sort ]
+  assertObject(query, 'Called SELECT with a non-object query')
+  assertArray(sort, 'Called SELECT with a non-array sort')
+
+  const [ conditions, values ] = where(query, [])
+
+  const order = []
+  for (const field of sort) {
+    if (field.toLowerCase().endsWith(' desc')) {
+      order.push(`${escape(field.slice(0, -5))} DESC`)
+    } else if (field.toLowerCase().endsWith(' asc')) {
+      order.push(`${escape(field.slice(0, -4))} ASC`)
+    } else {
+      order.push(escape(field))
+    }
+  }
+
+  const orderby = order.length == 0 ? '' : ` ORDER BY ${order.join(',')}`
+
+  let sql = `SELECT * FROM ${escape(schema)}.${escape(table)}${conditions}${orderby}`
+
+  if (offset && (offset > 0)) {
+    sql += ` OFFSET $${values.length + 1}`
+    values.push(Math.floor(offset))
+  }
+
+  if (limit && (limit > 0)) {
+    sql += ` LIMIT $${values.length + 1}`
+    values.push(Math.floor(limit))
+  }
+
+  return [ sql, values ]
+}
+
+/** Prepare an `UPDATE` statement for a table */
+function update(
+    schema: string,
+    table: string,
+    query: Record<string, any>,
+    patch: Record<string, any>,
+): Query {
+  assertObject(query, 'Called UPDATE with a non-object query')
+  assertObject(patch, 'Called UPDATE with a non-object patch')
+
+  const patches = []
+  const values = []
+
+  for (const [ column, value ] of Object.entries(patch)) {
+    if (value === undefined) continue
+    const index = values.push(value)
+    patches.push(`${escape(column)}=$${index}`)
+  }
+
+  if (patches.length === 0) return select(schema, table, query, [], 0, 0)
+
+  const [ conditions, , count ] = where(query, values)
+  assert(count > 0, 'Cowardly refusing to run UPDATE with empty query')
+
+  const statement = `UPDATE ${escape(schema)}.${escape(table)} SET ${patches.join()}${conditions} RETURNING *`
+  return [ statement, values ]
+}
+
+/** Prepare a `DELETE` statement for a table */
+function del(
+    schema: string,
+    table: string,
+    query: Record<string, any>,
+): Query {
+  assertObject(query, 'Called DELETE with a non-object query')
+
+  const [ conditions, values, count ] = where(query, [])
+
+  assert(count > 0, 'Cowardly refusing to run DELETE with empty query')
+
+  return [ `DELETE FROM ${escape(schema)}.${escape(table)}${conditions} RETURNING *`, values ]
+}
+
+/* ===== MODEL IMPLEMENTATION =============================================== */
+
+class ModelImpl<Table extends Record<string, ColumnDefinition>> implements Model<Table> {
+  private _connection: PGQueryable
+  private _schema: string
+  private _table: string
+
+  constructor(connection: PGQueryable, name: string) {
+    this._connection = connection
+
+    const [ schemaOrTable, maybeTable, ...extra ] = name.split('.')
+    assert(extra.length === 0, `Invalid table name "${name}"`)
+
+    const [ schema, table ] = maybeTable ?
+        [ schemaOrTable, maybeTable ] :
+        [ 'public', schemaOrTable ]
+    assert(table, `Invalid table name "${name}"`)
+
+    this._schema = schema || 'public'
+    this._table = table
+  }
+
+  async create(
+      data: InferInsertType<Table>,
+  ): Promise<InferSelectType<Table>> {
+    const [ sql, params ] = insert(this._schema, this._table, data)
+    const result = await this._connection.query<InferSelectType<Table>>(sql, params)
+    return result.rows[0]!
+  }
+
+  async upsert<K extends InferUpdateType<Table>>(
+      keys: K,
+      data: Omit<InferInsertType<Table>, keyof K>,
+  ): Promise<InferSelectType<Table>> {
+    const [ sql, params ] = upsert(this._schema, this._table, keys, data)
+    const result = await this._connection.query<InferSelectType<Table>>(sql, params)
+    return result.rows[0]!
+  }
+
+  async read(
+      query: InferUpdateType<Table> = {},
+      sort: InferSort<Table> | InferSort<Table>[] = [],
+      offset: number = 0,
+      limit: number = 0,
+  ): Promise<InferSelectType<Table>[]> {
+    const [ sql, params ] = select(this._schema, this._table, query, sort, offset, limit)
+    const result = await this._connection.query<InferSelectType<Table>>(sql, params)
+    return result.rows
+  }
+
+  async find(
+      query?: InferUpdateType<Table>,
+      sort?: InferSort<Table> | InferSort<Table>[],
+  ): Promise<InferSelectType<Table> | undefined> {
+    const result = await this.read(query, sort, 0, 1)
+    return result[0]
+  }
+
+  async update(
+      query: InferUpdateType<Table>,
+      patch: InferUpdateType<Table>,
+  ): Promise<InferSelectType<Table>[]> {
+    const [ sql, params ] = update(this._schema, this._table, query, patch)
+    const result = await this._connection.query<InferSelectType<Table>>(sql, params)
+    return result.rows
+  }
+
+  async delete(
+      query: InferUpdateType<Table>,
+  ): Promise<number> {
+    const [ sql, params ] = del(this._schema, this._table, query)
+    const result = await this._connection.query(sql, params)
+    return result.rowCount
+  }
+}
+
+/* ========================================================================== *
+ * EXPORTS                                                                    *
+ * ========================================================================== */
+
+/** Escape a PostgreSQL identifier (table, column, ... names) */
+export function escape(str: string): string {
+  return `"${str.replaceAll('"', '""').trim()}"`
+}
+
+export const Model: ModelConstructor = ModelImpl

package/src/persister.ts

@@ -0,0 +1,147 @@
+import { PGClient } from '@juit/pgproxy-client'
+
+import { Model } from './model'
+
+import type { PGQueryable, PGResult, PGTransactionable } from '@juit/pgproxy-client'
+import type { Registry } from '@juit/pgproxy-types'
+import type { ColumnDefinition } from './model'
+
+/* ========================================================================== *
+ * TYPES                                                                      *
+ * ========================================================================== */
+
+/* Infer the `Model` type from a schema and column name */
+export type InferModelType<Schema, Table extends string & keyof Schema> =
+  Schema[Table] extends Record<string, ColumnDefinition> ?
+    Model<Schema[Table]> :
+  never
+
+export interface ModelProvider<Schema> {
+  // Syntax sugar: "Table" here is not bound to "keyof Schema" as we want to
+  // return "never" in case the table does not exist in our schema, rather than
+  // a "Model" bound to the union of all tables in the schema...
+  in<Table extends string>(table: Table & keyof Schema): InferModelType<Schema, Table & keyof Schema>
+}
+
+/**
+ * A query interface guaranteeing that all operations will be performed on the
+ * _same_ database connection (transaction safe)
+ */
+export interface Connection<Schema> extends ModelProvider<Schema>, PGTransactionable {
+  /**
+   * Return the {@link Model} view associated with the specified table.
+   *
+   * All operations performed by this {@link Model} will share the same
+   * {@link Connection} (transaction safe).
+   */
+  in<Table extends string>(table: Table & keyof Schema): InferModelType<Schema, Table & keyof Schema>
+}
+
+/** A consumer for a {@link Connection} */
+export type Consumer<Schema, T> = (connection: Connection<Schema>) => T | PromiseLike<T>
+
+/** Our main `Persister` interface */
+export interface Persister<Schema> extends ModelProvider<Schema>, PGClient {
+  /** Ping... Just ping the database. */
+  ping(): Promise<void>;
+
+  /**
+   * Connect to the database to execute a number of different queries.
+   *
+   * The `consumer` will be passed a {@link Connection} instance backed by the
+   * _same_ connection to the database, therefore transactions can be safely
+   * executed in the context of the consumer function itself.
+   */
+  connect<T>(consumer: Consumer<Schema, T>): Promise<T>
+
+  /**
+   * Return the {@link Model} view associated with the specified table.
+   *
+   * All operations performed by this {@link Model} will potentially use
+   * different connections to the database (not transaction safe).
+   */
+  in<Table extends string>(table: Table & keyof Schema): InferModelType<Schema, Table & keyof Schema>
+}
+
+/** Constructor for {@link Persister} instances */
+export interface PersisterConstructor {
+  new <Schema = Record<string, Record<string, ColumnDefinition>>>(url?: string | URL): Persister<Schema>
+}
+
+/* ========================================================================== *
+ * IMPLEMENTATION                                                             *
+ * ========================================================================== */
+
+class ConnectionImpl<Schema> implements Connection<Schema> {
+  constructor(
+      private _queryable: PGQueryable,
+  ) {}
+
+  async begin(): Promise<this> {
+    await this._queryable.query('BEGIN')
+    return this
+  }
+
+  async commit(): Promise<this> {
+    await this._queryable.query('COMMIT')
+    return this
+  }
+
+  async rollback(): Promise<this> {
+    await this._queryable.query('ROLLBACK')
+    return this
+  }
+
+  query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(text: string, params: any[] | undefined = []): Promise<PGResult<Row, Tuple>> {
+    return this._queryable.query(text, params)
+  }
+
+  in<Table extends string>(table: Table & keyof Schema): InferModelType<Schema, Table & keyof Schema> {
+    return new Model(this._queryable, table) as InferModelType<Schema, Table & keyof Schema>
+  }
+}
+
+class PersisterImpl<Schema> implements PGClient, Persister<Schema> {
+  private _client: PGClient
+
+  constructor(url?: string | URL) {
+    this._client = new PGClient(url)
+  }
+
+  get registry(): Registry {
+    return this._client.registry
+  }
+
+  async ping(): Promise<void> {
+    await this._client.query('SELECT now()')
+  }
+
+  async query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(text: string, params: any[] | undefined = []): Promise<PGResult<Row, Tuple>> {
+    const result = this._client.query<Row, Tuple>(text, params)
+    return result
+  }
+
+  async destroy(): Promise<void> {
+    await this._client.destroy()
+  }
+
+  async connect<T>(consumer: Consumer<Schema, T>): Promise<T> {
+    return await this._client.connect((conn) => consumer(new ConnectionImpl(conn)))
+  }
+
+  in<Table extends string>(table: Table & keyof Schema): InferModelType<Schema, Table & keyof Schema> {
+    return new Model(this._client, table) as InferModelType<Schema, Table & keyof Schema>
+  }
+}
+
+/* ========================================================================== *
+ * EXPORTS                                                                    *
+ * ========================================================================== */
+
+export const Persister: PersisterConstructor = PersisterImpl