@juit/pgproxy-persister 1.0.0

package/README.md

@@ -0,0 +1,228 @@
+# PostgreSQL Proxy Client (Persister Interface)
+
+The persister interface for PostgreSQL Proxy is a higher-level interface
+offering (on top of the usual connection and query interface) a CRUD
+abstraction over database tables and few utility methods.
+
+* [Connecting](#connecting)
+* [Schema Definition](#schema-defintion)
+* [Model Views](#model-views)
+  * [Create](#create)
+  * [Upsert](#upsert)
+  * [Read](#read)
+  * [Find](#find)
+  * [Update](#update)
+  * [Delete](#delete)
+* [Pinging the database](#pinging-the-database)
+* [PGProxy](https://github.com/juitnow/juit-pgproxy/blob/main/README.md)
+* [Copyright Notice](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
+* [License](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
+
+
+
+### Connecting
+
+In the code, you can simply depend on the `Persister` class:
+
+```ts
+import { Persister } from '@juit/pgproxy-persister'
+
+const client = new Persister()
+```
+
+As with the standard client (`PGClient`) persisters can be constructed with a
+`url` as a parameter, indicating the endpoint of the connection _and_
+the specific client to be used.
+
+
+
+### Schema Definition
+
+The `Persister` interface (and the `Model`s bound to it) is a _generic_
+interface. The `Schema` type parameter can be used to provide a fully typed
+view over the columns (and related `Model`s) it manages.
+
+Formally, the `Schema` is a type mapping table and column names to column
+definitions. Each column definition is a type containing the following
+properties:
+
+* `type`: the _type_ of the column
+* `isNullable` _(optional)_: if `true` the column is _nullable_ and henceforth
+  the `null` value can be used in lieu of the `type` above.
+* `hasDefault` _(optional)_: if `true` the column _specifies a default value_
+  and therefore can be omitted in create operations.
+
+An example of a `Schema` is as follows:
+
+```ts
+/** Definition for all modelable columns */
+export interface MySchema {
+  /** Columns for the `users` table */
+  users: {
+    /** Definition for the `id` column in `users` */
+    id: { type: number, hasDefault: true } // not nullable, but has default
+    /** Definition for the `email` column in `users` */
+    email: { type: string } // not nullable, no default, required creating
+    /** Definition for the `age` column in `users` */
+    age: { type: number, isNullable: true, hasDefault: false }
+
+    // ... all other columns
+  },
+
+  // ... all other tables
+}
+```
+
+The `@juit/pgproxy-utils` comes with a useful schema generator, querying a
+database for all of its tables and generating a proper TypeScript interface.
+
+
+
+### Model views
+
+Model views offer a very basic interface to **C**reate, **R**ead, **U**pdate
+and **D**elete data from a table.
+
+A _CRUD_ model can be obtained by calling the `in(tableName)` on a `Persister`
+or `connection` object, for example:
+
+```ts
+const model = persister.in('myTable')
+model.create({ ... })
+model.delete({ ... })
+
+persister.connect(async (connection) => {
+  const model = connection.in('myTable')
+  await model.create({ ... })
+  await model.delete({ ... })
+})
+```
+
+#### Create
+
+The model's `create(object)` function will create `INSERT INTO ... RETURNING *`
+statements based on the specified object.
+
+Each key in the object will represent a _column name_ and its associated value
+will be inserted in place.
+
+This function will return (obviously) the values inserted, including any default
+value calculated by the database.
+
+```typescript
+persisterOrConnection.in('myTable').create({ myString: 'foo', myNumber: 123 })
+// INSERT INTO "myTable" ("myString", "myNumber") VALUES ('foo', 123) RETURNING *
+
+persisterOrConnection.in('myTable').create({})
+// INSERT INTO "myTable" DEFAULT VALUES RETURNING *
+```
+
+#### Upsert
+
+The model's `upsert(keys, data)` function will create upsert statements like
+`INSERT INTO ... ON CONFLICT (...) DO UPDATE ... RETURNING *`.
+
+The `keys` object passed as a first argument indicates the columns (and values
+to set) for which conflicts are to be detected, while `data` is an object
+containing other columns to update.
+
+This function will return the values inserted and/or updated.
+
+```typescript
+persisterOrConnection.in('myTable').upsert({
+  myKey: 'myValue', anotherKey: 'anotherValue'
+}, {
+  myString: 'foo', myNumber: 123
+})
+// INSERT INTO "myTable" ("myKey",   "anotherKey",   "myString", "myNumber")
+//      VALUES           ('myValue', 'anotherValue', 'foo',      123)
+// ON CONFLICT ("myKey", "anotherKey") DO UPDATE
+//         SET "myString"='foo',
+//             "myNumber"=123
+//   RETURNING *
+```
+
+#### Read
+
+The model's `read(query, sort)` function will create `SELECT * FROM ...`
+statements based on the specified query and sort parameters.
+
+Each key/value mapping in the query object will be mapped to a `WHERE key=value`
+statement part.
+
+The sort parameter must be an `Array` of `string`(s) containing the column name
+and (optionally) the keywords `ASC` or `DESC`:
+
+```ts
+persisterOrConnection.in('myTable').read({ myString: 'foo', myNumber: 123 }, [
+  'mySortColumn',
+  'anotherSortColumn ASC',
+  'yetAnotherSortColumn DESC',
+])
+// SELECT * FROM "myTable" WHERE "myString"='foo' AND "myNumber"=123
+// ORDER BY "mySortColumn", "anotherSortColumn" ASC, "yetAnotherSortColumn" DESC
+```
+
+#### Find
+
+Similar to `read(...)` this method will return the _first_ result of the
+generated `SELECT` query, or _undefined_ in case of no results:
+
+```ts
+persisterOrConnection.in('myTable').find({ myString: 'foo', myNumber: 123 }, [
+  'mySortColumn',
+  'anotherSortColumn ASC',
+  'yetAnotherSortColumn DESC',
+])
+// SELECT * FROM "myTable" WHERE "myString"='foo' AND "myNumber"=123
+// ORDER BY "mySortColumn", "anotherSortColumn" ASC, "yetAnotherSortColumn" DESC
+// LIMIT 1
+```
+
+#### Update
+
+The model's `update(query, patch)` function will create
+`UPDATE ... WHERE ... SET ...  RETURNING *` statements.
+
+* the `query` parameter will work as in [read](#read), generating `WHERE ...`
+  statement parts.
+* the `patch` parameter will work similarly to [create](#create), generating
+  `SET ...=...` statement parts.
+
+This function will _cowardly_ fail when the `query` parameter is an empty object
+(by design, we don't allow modification of _all_ rows in a database).
+
+This function will return an `Array` of all rows modified by this call.
+
+```javascript
+persisterOrConnection.in('myTable').update({ myString: 'foo'}, { myNumber: 123 })
+// UPDATE "myTable" SET "myNumber=123 WHERE "myString"='foo' RETURNING *
+```
+
+#### Delete
+
+The model's `delete(query)` function will create
+`DELETE FROM ... WHERE ... RETURNING *` statements.
+
+* the `query` parameter will work as in [read](#read), generating `WHERE ...`
+  statement parts.
+* the `patch` parameter will work similarly to [create](#create), generating
+  `SET ...=...` statement parts.
+
+This function will _cowardly_ fail when the `query` parameter is an empty object
+(by design, we don't allow deletion of _all_ rows in a database).
+
+This function will return the _number of rows_ deleted by the query.
+
+```javascript
+persisterOrConnection.in('myTable').delete({ myString: 'foo'})
+// DELETE FROM "myTable" WHERE "myString"='foo' RETURNING *
+```
+
+
+
+### Pinging the database
+
+The `ping()` method on `Persister` is a simple shortcut to
+`void query('SELECT now()')` and can be used to ping the database (for health
+checks, connectivity checks, keepalives, ...).

package/dist/index.cjs

@@ -0,0 +1,27 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var src_exports = {};
+module.exports = __toCommonJS(src_exports);
+__reExport(src_exports, require("./model.cjs"), module.exports);
+__reExport(src_exports, require("./persister.cjs"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./model.cjs"),
+  ...require("./persister.cjs")
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAAA;AACA,wBAAc,wBADd;AAEA,wBAAc,4BAFd;",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './model';
+export * from './persister';

package/dist/index.mjs

@@ -0,0 +1,4 @@
+// index.ts
+export * from "./model.mjs";
+export * from "./persister.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";AACA,cAAc;AACd,cAAc;",
+  "names": []
+}

package/dist/model.cjs

@@ -0,0 +1,211 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// model.ts
+var model_exports = {};
+__export(model_exports, {
+  Model: () => Model,
+  escape: () => escape
+});
+module.exports = __toCommonJS(model_exports);
+function assert(assertion, message) {
+  if (!assertion)
+    throw new Error(message);
+}
+function assertArray(value, message) {
+  assert(Array.isArray(value), message);
+}
+function assertObject(value, message) {
+  assert(value && typeof value === "object", message);
+}
+function where(query, params) {
+  const conditions = [];
+  let count = 0;
+  for (const [column, value] of Object.entries(query)) {
+    if (value === void 0)
+      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
+  ];
+}
+function insert(schema, table, 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 === void 0)
+      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
+  ];
+}
+function upsert(schema, table, keys, data) {
+  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");
+  const object = { ...keys, ...data, ...keys };
+  const columns = [];
+  const placeholders = [];
+  const values = [];
+  for (const [column, value] of Object.entries(object)) {
+    if (value === void 0)
+      continue;
+    const index = columns.push(`${escape(column)}`);
+    placeholders.push(`$${index}`);
+    values.push(value);
+  }
+  const conflictKeys = [];
+  for (const [column, value] of Object.entries(keys)) {
+    if (value !== void 0)
+      conflictKeys.push(escape(column));
+  }
+  const updates = [];
+  for (const [column, value] of Object.entries(data)) {
+    if (value === void 0)
+      continue;
+    updates.push(`${escape(column)}=$${updates.length + columns.length + 1}`);
+    values.push(value);
+  }
+  return [
+    `INSERT INTO ${escape(schema)}.${escape(table)} (${columns.join()}) VALUES (${placeholders.join()}) ON CONFLICT (${conflictKeys.join(",")}) DO UPDATE SET ${updates.join(",")} RETURNING *`,
+    values
+  ];
+}
+function select(schema, table, query, sort, offset, limit) {
+  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];
+}
+function update(schema, table, query, patch) {
+  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 === void 0)
+      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];
+}
+function del(schema, table, 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];
+}
+var ModelImpl = class {
+  _connection;
+  _schema;
+  _table;
+  constructor(connection, name) {
+    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) {
+    const [sql, params] = insert(this._schema, this._table, data);
+    const result = await this._connection.query(sql, params);
+    return result.rows[0];
+  }
+  async upsert(keys, data) {
+    const [sql, params] = upsert(this._schema, this._table, keys, data);
+    const result = await this._connection.query(sql, params);
+    return result.rows[0];
+  }
+  async read(query = {}, sort = [], offset = 0, limit = 0) {
+    const [sql, params] = select(this._schema, this._table, query, sort, offset, limit);
+    const result = await this._connection.query(sql, params);
+    return result.rows;
+  }
+  async find(query, sort) {
+    const result = await this.read(query, sort, 0, 1);
+    return result[0];
+  }
+  async update(query, patch) {
+    const [sql, params] = update(this._schema, this._table, query, patch);
+    const result = await this._connection.query(sql, params);
+    return result.rows;
+  }
+  async delete(query) {
+    const [sql, params] = del(this._schema, this._table, query);
+    const result = await this._connection.query(sql, params);
+    return result.rowCount;
+  }
+};
+function escape(str) {
+  return `"${str.replaceAll('"', '""').trim()}"`;
+}
+var Model = ModelImpl;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Model,
+  escape
+});
+//# sourceMappingURL=model.cjs.map

package/dist/model.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/model.ts"],
+  "mappings": "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",
+  "names": []
+}

package/dist/model.d.ts

@@ -0,0 +1,95 @@
+import type { PGQueryable } from '@juit/pgproxy-client';
+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<{
+    [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'];
+} & {
+    [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' | ''}`;
+/** 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>;
+}
+/** Escape a PostgreSQL identifier (table, column, ... names) */
+export declare function escape(str: string): string;
+export declare const Model: ModelConstructor;
+export {};