@graffy/pg 0.15.17 → 0.15.19-alpha.2

package/Readme.md

@@ -2,19 +2,41 @@
 
 The standard Postgres module for Graffy. Each instance this module mounts a Postgres table as a Graffy subtree.
 
+Requires the [pg](https://github.com/brianc/node-postgres) library to be installed as a peer dependency.
+
 ## Usage
 
 ```js
 import pg from '@graffy/pg';
+import Graffy from '@graffy/core';
+import link from '@graffy/link';
 
-graffyStore.use(pg(options));
+const store = new Graffy();
+store.use(path, pg(options));
 ```
 
-Uses the [pg](https://github.com/brianc/node-postgres) library.
+### Options
+
+- `table`, the name of the table. If not provided, the last segment of the `path` is used. This table must exist.
+- `idCol`: the name of the column to use as ID. Defaults to `id`. This column must exist and be the primary key or have a unique constraint.
+- `verCol`: the name of the column to store the Graffy version number. This column must exist, and must have a `DEFAULT` SQL expression defined - this expression is evaluated to calculate the version number. Graffy versions must monotonically increase, so this expression is typically based on `CURRENT_TIMESTAMP`.
+- `connection`: a [pg](https://github.com/brianc/node-postgres) Client or Pool object (recommended), or the arguments for constructing a new Pool object. Optional.
+
+### Database connection
+
+Graffy Postgres can be configured to use a specific pg.Client object on a per-request basis, by including a `pgClient` property on the read or write options. This is useful for implementing transactions, partitioning, row-level security, etc.
+
+If no `pgClient` is provided for a particular operation, Graffy Postgres falls back to the "global" pg.Client or pg.Pool object defined in the `connection` parameter in the initialization options. If no `connection` parameter was passed, a new pg.Pool will be created using PSQL environment variables.
+
+## Data model
+
+Graffy Postgres interprets each property as the name of a column, except for `$count`, `$sum` etc. as described in the aggregation section below.
+
+It also interprets the `$key` as specifying filtering, sorting, pagination and aggregation parameters.
 
-### Query filters
+### Filters
 
-Query filters are passed in `$key` and are JSON-based, somewhat like MongoDB.
+Query filters are JSON-based, somewhat like MongoDB.
 
 1. Filters expressions follow a **property**, **operator**, **value** order. Values are scalar values (strings or numbers).
 2. Property names are always object keys. They may be strings with dots `.`.

package/index.cjs

@@ -158,7 +158,6 @@ function simplify(node) {
   }
   return node;
 }
-const nowTimestamp = sql__default["default"]`cast(extract(epoch from now()) as integer)`;
 const getJsonBuildTrusted = (variadic) => {
   const args = sql.join(Object.entries(variadic).map(([name, value]) => {
     return sql__default["default"]`'${sql.raw(name)}', ${getJsonBuildValue(value)}`;
@@ -226,14 +225,14 @@ function castValue(value, type, name, isPut) {
 const getInsert = (row, options) => {
   const cols = [];
   const vals = [];
-  Object.entries(row).filter(([col]) => col !== options.verCol && col[0] !== "$").concat([[options.verCol, nowTimestamp]]).forEach(([col, val]) => {
+  Object.entries(row).filter(([col]) => col !== options.verCol && col[0] !== "$").concat([[options.verCol, sql__default["default"]`default`]]).forEach(([col, val]) => {
     cols.push(sql__default["default"]`"${sql.raw(col)}"`);
     vals.push(castValue(val, options.schema.types[col], col, row.$put));
   });
   return { cols: sql.join(cols, ", "), vals: sql.join(vals, ", ") };
 };
 const getUpdates = (row, options) => {
-  return sql.join(Object.entries(row).filter(([col]) => col !== options.idCol && col[0] !== "$").map(([col, val]) => sql__default["default"]`"${sql.raw(col)}" = ${castValue(val, options.schema.types[col], col, row.$put)}`).concat(sql__default["default"]`"${sql.raw(options.verCol)}" = ${nowTimestamp}`), ", ");
+  return sql.join(Object.entries(row).filter(([col]) => col !== options.idCol && col[0] !== "$").map(([col, val]) => sql__default["default"]`"${sql.raw(col)}" = ${castValue(val, options.schema.types[col], col, row.$put)}`).concat(sql__default["default"]`"${sql.raw(options.verCol)}" = default`), ", ");
 };
 function getJsonUpdate(object, col, path) {
   if (!object || typeof object !== "object" || Array.isArray(object) || object.$put) {
@@ -325,18 +324,18 @@ function getSql(filter, options) {
   }
   return getNodeSql(getAst(filter));
 }
-const getIdMeta = ({ idCol }) => getJsonBuildTrusted({
+const getIdMeta = ({ idCol, verDefault }) => getJsonBuildTrusted({
   $key: sql__default["default"]`"${sql.raw(idCol)}"`,
-  $ver: nowTimestamp
+  $ver: sql.raw(verDefault)
 });
-const getArgMeta = (key, prefix, idCol) => getJsonBuildTrusted({
+const getArgMeta = (key, { prefix, idCol, verDefault }) => getJsonBuildTrusted({
   $key: key,
   $ref: sql__default["default"]`jsonb_build_array(${sql.join(prefix.map((k) => sql__default["default"]`${k}::text`))}, "${sql.raw(idCol)}")`,
-  $ver: nowTimestamp
+  $ver: sql.raw(verDefault)
 });
-const getAggMeta = (key, $group) => getJsonBuildTrusted({
+const getAggMeta = (key, $group, { verDefault }) => getJsonBuildTrusted({
   $key: sql.join([key, getJsonBuildTrusted({ $group })].filter(Boolean), " || "),
-  $ver: nowTimestamp
+  $ver: sql.raw(verDefault)
 });
 function getArgSql(_a, options) {
   var _b = _a, { $first, $last, $after, $before, $since, $until, $all, $cursor: _ } = _b, rest = __objRest(_b, ["$first", "$last", "$after", "$before", "$since", "$until", "$all", "$cursor"]);
@@ -345,7 +344,7 @@ function getArgSql(_a, options) {
   if ($order && $group) {
     throw Error("pg_arg.order_and_group_unsupported in " + prefix);
   }
-  const meta = (key2) => $group ? getAggMeta(key2, $group) : getArgMeta(key2, prefix, idCol);
+  const meta = (key2) => $group ? getAggMeta(key2, $group, options) : getArgMeta(key2, options);
   const groupCols = Array.isArray($group) && $group.length && $group.map(lookup);
   const group = groupCols ? sql.join(groupCols, ", ") : void 0;
   const hasRangeArg = $before || $after || $since || $until || $first || $last || $all || $order;
@@ -528,24 +527,34 @@ class Db {
   async ensureSchema(tableOptions) {
     if (tableOptions.schema)
       return;
-    const { table } = tableOptions;
-    const types = (await this.query(sql__default["default"]`SELECT jsonb_object_agg(
-          column_name,
-          udt_name
-      )
-      FROM information_schema.columns
-      WHERE
+    const { table, verCol } = tableOptions;
+    const tableSchema = (await this.query(sql__default["default"]`
+        SELECT table_schema
+        FROM information_schema.tables
+        WHERE table_name = ${table}
+        ORDER BY array_position(current_schemas(false)::text[], table_schema::text) ASC
+        LIMIT 1`)).rows[0][0];
+    const types = (await this.query(sql__default["default"]`
+        SELECT jsonb_object_agg(column_name, udt_name)
+        FROM information_schema.columns
+        WHERE
           table_name = ${table} AND
-          table_schema = (
-              SELECT table_schema
-              FROM information_schema.tables
-              WHERE table_name = ${table}
-              ORDER BY array_position(current_schemas(false)::text[], table_schema::text) ASC
-              LIMIT 1)`)).rows[0][0];
+          table_schema = ${tableSchema}`)).rows[0][0];
     if (!types)
       throw Error(`pg.missing_table ${table}`);
+    const verDefault = (await this.query(sql__default["default"]`
+        SELECT column_default
+        FROM information_schema.columns
+        WHERE
+          table_name = ${table} AND
+          table_schema = ${tableSchema} AND
+          column_name = ${verCol}`)).rows[0][0];
+    if (!verDefault) {
+      throw Error(`pg.verCol_without_default ${verCol}`);
+    }
     log("ensureSchema", types);
     tableOptions.schema = { types };
+    tableOptions.verDefault = verDefault;
   }
   async read(rootQuery, tableOptions) {
     const idQueries = {};
@@ -621,7 +630,7 @@ class Db {
     return result;
   }
 }
-const pg = ({ table, idCol, verCol, connection, schema }) => (store) => {
+const pg = ({ table, idCol, verCol, connection, schema, verDefault }) => (store) => {
   store.on("read", read);
   store.on("write", write);
   const prefix = store.path;
@@ -630,7 +639,8 @@ const pg = ({ table, idCol, verCol, connection, schema }) => (store) => {
     table: table || prefix[prefix.length - 1] || "default",
     idCol: idCol || "id",
     verCol: verCol || "updatedAt",
-    schema
+    schema,
+    verDefault
   };
   const defaultDb = new Db(connection);
   function read(query, options, next) {

package/index.mjs

@@ -150,7 +150,6 @@ function simplify(node) {
   }
   return node;
 }
-const nowTimestamp = sql`cast(extract(epoch from now()) as integer)`;
 const getJsonBuildTrusted = (variadic) => {
   const args = join(Object.entries(variadic).map(([name, value]) => {
     return sql`'${raw(name)}', ${getJsonBuildValue(value)}`;
@@ -218,14 +217,14 @@ function castValue(value, type, name, isPut) {
 const getInsert = (row, options) => {
   const cols = [];
   const vals = [];
-  Object.entries(row).filter(([col]) => col !== options.verCol && col[0] !== "$").concat([[options.verCol, nowTimestamp]]).forEach(([col, val]) => {
+  Object.entries(row).filter(([col]) => col !== options.verCol && col[0] !== "$").concat([[options.verCol, sql`default`]]).forEach(([col, val]) => {
     cols.push(sql`"${raw(col)}"`);
     vals.push(castValue(val, options.schema.types[col], col, row.$put));
   });
   return { cols: join(cols, ", "), vals: join(vals, ", ") };
 };
 const getUpdates = (row, options) => {
-  return join(Object.entries(row).filter(([col]) => col !== options.idCol && col[0] !== "$").map(([col, val]) => sql`"${raw(col)}" = ${castValue(val, options.schema.types[col], col, row.$put)}`).concat(sql`"${raw(options.verCol)}" = ${nowTimestamp}`), ", ");
+  return join(Object.entries(row).filter(([col]) => col !== options.idCol && col[0] !== "$").map(([col, val]) => sql`"${raw(col)}" = ${castValue(val, options.schema.types[col], col, row.$put)}`).concat(sql`"${raw(options.verCol)}" = default`), ", ");
 };
 function getJsonUpdate(object, col, path) {
   if (!object || typeof object !== "object" || Array.isArray(object) || object.$put) {
@@ -317,18 +316,18 @@ function getSql(filter, options) {
   }
   return getNodeSql(getAst(filter));
 }
-const getIdMeta = ({ idCol }) => getJsonBuildTrusted({
+const getIdMeta = ({ idCol, verDefault }) => getJsonBuildTrusted({
   $key: sql`"${raw(idCol)}"`,
-  $ver: nowTimestamp
+  $ver: raw(verDefault)
 });
-const getArgMeta = (key, prefix, idCol) => getJsonBuildTrusted({
+const getArgMeta = (key, { prefix, idCol, verDefault }) => getJsonBuildTrusted({
   $key: key,
   $ref: sql`jsonb_build_array(${join(prefix.map((k) => sql`${k}::text`))}, "${raw(idCol)}")`,
-  $ver: nowTimestamp
+  $ver: raw(verDefault)
 });
-const getAggMeta = (key, $group) => getJsonBuildTrusted({
+const getAggMeta = (key, $group, { verDefault }) => getJsonBuildTrusted({
   $key: join([key, getJsonBuildTrusted({ $group })].filter(Boolean), " || "),
-  $ver: nowTimestamp
+  $ver: raw(verDefault)
 });
 function getArgSql(_a, options) {
   var _b = _a, { $first, $last, $after, $before, $since, $until, $all, $cursor: _ } = _b, rest = __objRest(_b, ["$first", "$last", "$after", "$before", "$since", "$until", "$all", "$cursor"]);
@@ -337,7 +336,7 @@ function getArgSql(_a, options) {
   if ($order && $group) {
     throw Error("pg_arg.order_and_group_unsupported in " + prefix);
   }
-  const meta = (key2) => $group ? getAggMeta(key2, $group) : getArgMeta(key2, prefix, idCol);
+  const meta = (key2) => $group ? getAggMeta(key2, $group, options) : getArgMeta(key2, options);
   const groupCols = Array.isArray($group) && $group.length && $group.map(lookup);
   const group = groupCols ? join(groupCols, ", ") : void 0;
   const hasRangeArg = $before || $after || $since || $until || $first || $last || $all || $order;
@@ -520,24 +519,34 @@ class Db {
   async ensureSchema(tableOptions) {
     if (tableOptions.schema)
       return;
-    const { table } = tableOptions;
-    const types = (await this.query(sql`SELECT jsonb_object_agg(
-          column_name,
-          udt_name
-      )
-      FROM information_schema.columns
-      WHERE
+    const { table, verCol } = tableOptions;
+    const tableSchema = (await this.query(sql`
+        SELECT table_schema
+        FROM information_schema.tables
+        WHERE table_name = ${table}
+        ORDER BY array_position(current_schemas(false)::text[], table_schema::text) ASC
+        LIMIT 1`)).rows[0][0];
+    const types = (await this.query(sql`
+        SELECT jsonb_object_agg(column_name, udt_name)
+        FROM information_schema.columns
+        WHERE
           table_name = ${table} AND
-          table_schema = (
-              SELECT table_schema
-              FROM information_schema.tables
-              WHERE table_name = ${table}
-              ORDER BY array_position(current_schemas(false)::text[], table_schema::text) ASC
-              LIMIT 1)`)).rows[0][0];
+          table_schema = ${tableSchema}`)).rows[0][0];
     if (!types)
       throw Error(`pg.missing_table ${table}`);
+    const verDefault = (await this.query(sql`
+        SELECT column_default
+        FROM information_schema.columns
+        WHERE
+          table_name = ${table} AND
+          table_schema = ${tableSchema} AND
+          column_name = ${verCol}`)).rows[0][0];
+    if (!verDefault) {
+      throw Error(`pg.verCol_without_default ${verCol}`);
+    }
     log("ensureSchema", types);
     tableOptions.schema = { types };
+    tableOptions.verDefault = verDefault;
   }
   async read(rootQuery, tableOptions) {
     const idQueries = {};
@@ -613,7 +622,7 @@ class Db {
     return result;
   }
 }
-const pg = ({ table, idCol, verCol, connection, schema }) => (store) => {
+const pg = ({ table, idCol, verCol, connection, schema, verDefault }) => (store) => {
   store.on("read", read);
   store.on("write", write);
   const prefix = store.path;
@@ -622,7 +631,8 @@ const pg = ({ table, idCol, verCol, connection, schema }) => (store) => {
     table: table || prefix[prefix.length - 1] || "default",
     idCol: idCol || "id",
     verCol: verCol || "updatedAt",
-    schema
+    schema,
+    verDefault
   };
   const defaultDb = new Db(connection);
   function read(query, options, next) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@graffy/pg",
   "description": "The standard Postgres module for Graffy. Each instance this module mounts a Postgres table as a Graffy subtree.",
   "author": "aravind (https://github.com/aravindet)",
-  "version": "0.15.17",
+  "version": "0.15.19-alpha.2",
   "main": "./index.cjs",
   "exports": {
     "import": "./index.mjs",
@@ -16,7 +16,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@graffy/common": "0.15.17",
+    "@graffy/common": "0.15.19-alpha.2",
     "sql-template-tag": "^4.1.0",
     "debug": "^4.3.3"
   },

package/types/index.d.ts

@@ -1,7 +1,8 @@
-export function pg({ table, idCol, verCol, connection, schema }: {
+export function pg({ table, idCol, verCol, connection, schema, verDefault }: {
     table?: string;
     idCol?: string;
     verCol?: string;
     connection?: any;
     schema?: any;
+    verDefault?: string;
 }): (store: any) => void;

package/types/sql/clauses.d.ts

@@ -1,5 +1,4 @@
 export function vertexSql(array: any): Sql;
-export const nowTimestamp: Sql;
 export function getJsonBuildTrusted(variadic: any): Sql;
 export function lookup(prop: any): Sql;
 export function getSelectCols(table: any, projection?: any): Sql;

package/types/sql/getMeta.d.ts

@@ -1,5 +1,12 @@
-export function getIdMeta({ idCol }: {
+export function getIdMeta({ idCol, verDefault }: {
     idCol: any;
+    verDefault: any;
+}): import("sql-template-tag").Sql;
+export function getArgMeta(key: any, { prefix, idCol, verDefault }: {
+    prefix: any;
+    idCol: any;
+    verDefault: any;
+}): import("sql-template-tag").Sql;
+export function getAggMeta(key: any, $group: any, { verDefault }: {
+    verDefault: any;
 }): import("sql-template-tag").Sql;
-export function getArgMeta(key: any, prefix: any, idCol: any): import("sql-template-tag").Sql;
-export function getAggMeta(key: any, $group: any): import("sql-template-tag").Sql;