@graffy/pg 0.15.11 → 0.15.13-alpha.1

package/Readme.md

@@ -10,9 +10,137 @@ import pg from '@graffy/pg';
 graffyStore.use(pg(options));
 ```
 
-Connection parameters should be set in environment variables. Uses the [pg](https://github.com/brianc/node-postgres) library.
+Uses the [pg](https://github.com/brianc/node-postgres) library.
 
-## Options
+### Query filters
 
-In this document, _property names_ and _paths_ refer to the structures in the Graffy graph objects, _columns_ refer to Postgres table columns and _args_ refer to structures in the filtering and pagination arguments of Graffy query objects.
+Query filters are passed in `$key` and 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 `.`.
+3. Operators are placed in objects as well and have a leading `$`.
+4. Values are JSON values.
+5. Multiple properties in an object are combined with `AND`. Items in an arrays are combined with `OR`.
+6. The supported operators are:
+    - `$eq`: optional in most cases.
+    - `$lt`, `$lte`, `$gt`, `$gte`: Ranges
+    - `$re`, `$ire`: Regex match (case sensitive and insensitive versions)
+    - `$text`: Full text search, always case insensitive
+    - `$not`: Modifies other filters or inverts a condition
+    - `$and`, `$or`: Combines conditions; optional in most cases
+    - `$all`, `$has`, `$any`: Apply conditions to the elements of a collection (list or map)
+
+#### Basic
+
+1. `{ foo: 5 }` and `{ foo: { $eq: 5 } }` compile to SQL `foo = 5`.
+2. `{ foo: { $gt: 5, $lt: 6 } }` becomes `foo > 5 AND foo < 6`.
+3. `{ foo: { $ire: '^wor.*' } }` becomes `foo ~* "^wor.*"`.
+4. `{ foo: { $text: 'potatoes' } }` becomes `foo @@ websearch_to_tsquery('potatoes')`.
+For this to work, `foo` must be a TSVector column.
+
+#### Or
+
+1. `{ foo: [5, 6] }` means *foo equals 5 or foo equals 6*, and the compiler is smart enough to simplify this to `foo IN (5, 6)`. There is no separate $in.
+2. `{ foo: [ 5, { $gt: 6 } ] }` becomes `foo = 5 OR foo > 6`
+3. `[ { foo: 6 }, { bar: 7 } ]` becomes `foo = 6 OR bar = 7`
+
+#### Not
+
+1. `{ foo: { $not: 6 } }` becomes `foo <> 6` (the SQL not equals operator)
+2. `{ foo: { $not: [5, 6] }` becomes `foo NOT IN (5, 6)`
+3. `{ foo: { $not: [ 5, { $gt: 6 } ] } }` becomes `NOT (foo = 5 OR foo > 6)`
+
+#### Logic
+
+1. By default, objects mean `AND` and arrays mean `OR`:
+`[ { foo: 5, bar: 6 }, { baz: 7, qux: 4 } ]` becomes
+`(foo = 5 AND bar = 6) OR (baz = 7 AND qux = 4)`
+2. Use `$and` and `$or` operators explicitly to use any structure in either context:
+    
+    `{ $and: [ { $or: { foo: 5, bar: 6 } }, { $or: { baz: 7, qux: 4 } } ] }` becomes
+    `(foo = 5 OR bar = 6) AND (baz = 7 OR qux = 4)`.
+
+#### Contains and Contained by
+
+1. `{ tags: { $cts: ['foo', 'bar'] } }` becomes `tags @> '{"foo","bar"}'`.
+Tags must contain both *foo* and *bar*. Note that the array of conditions here does not have `OR` semantics.
+2. `{ tags: { $ctd: ['foo', 'bar', 'baz'] } }` becomes `tags <@ '{"foo","bar","baz"}'`.
+Every tag must be one of *foo*, *bar* or *baz*.
+
+#### Notes
+
+1. We drop several MongoDB operators while retaining the capability:
+    - `$ne`: Use $not instead.
+    - `$in`: Use an array of values; it is a combination of implicit $or and $eq.
+    - `$nin`: Use $not and an array of values.
+    - `$exists`: Use `null` or `{ $not: null }`. Postgres does not distinguish between `undefined` and `null`, and neither does Graffy (in this context at least; it's complicated.)
+2. Graffy `$has` is equivalent to MongoDB `$all` (each of the provided conditions is met by  at least one element in the array). Graffy `$all` (every element of the array meets a condition) has no direct MongoDB equivalent, but can be expressed as `{ $not: { $elemMatch: { $not: (cond) } } }`
+3. Graffy has a separate operator for case-insensitive regex, and configures the text search locale in the database object rather than the query. This makes MongoDB's regex `$options`, full text `$language` etc. unnecessary.
+4. Graffy does not have equivalents for MongoDB operators `$type`, `$expr`, `$jsonSchema`, `$where`, `$mod`, `$size` and the geospatial operators.
+
+### Order by
+
+The root of the Graffy filter object must be an object. (Use `$or` if required.) The property `$order` specifies the order. Its value must be an array of order specifiers, each of which may be a string property name or an object with property names, sort direction, collation and text search relevance. (TBD)
+
+### Full Text Search
+
+A full-text search query typically has three requirements:
+
+- Filter: `{ tsv: { $text: 'query' } }`. Return only results that match.
+- Order: `{ $order: [{ $text: ['tsv', 'query'] }], ... }`. Sort results by relevance.
+- Projection: `{ tsv: { query: true } }`. Return snippets of the document surrounding matches.
+
+In all three, `tsv` is a computed column of type TSVector.
+
+### Aggregations
+
+In Graffy PG, aggregations are specified using the `$group` argument in $key, and special properties like `$count`, `$sum` etc. in the projection. `$group` may be `true` or an array.
+
+Consider a table of books with columns `authorId` and `copiesSold`. We want the to compute aggregates on the `copiesSold` column.
+
+#### Without Group By
+
+Let's say we want the total copies sold of all the books in our database. We use `$group: true`, like:
+
+```js
+{
+  books: {
+  $key: { $group: true },
+  $sum: { copiesSold: true }
+}
+```
+
+Note how the field to sum is specified; this way, multiple fields may be specified.
+
+As always, the result will mirror the query:
+
+```js
+books: [{
+  $key: { $group: true },
+  $sum: { copiesSold: 12345 }
+}]
+```
+
+#### With Group By
+
+Now let's say we want the separate totals for each author. As we might have a very large number of authors, we might need to paginate over the results.
+
+The grouping properties (e.g. `authorId`) may also be included in the projection, and these values may even be used to construct links.
+
+```js
+{
+  books: {
+  $key: { $group: ['authorId'], $first: 30 },
+  authorId: true,
+  author: { namme: true }, // Link to ['users', authorId]
+  $sum: { copiesSold: true }
+}
+```
+
+#### Aggregate functions
+
+Graffy supports the following aggregate functions.
+
+- `$count` of rows; this is just specified as `$count: true`, without any fields under it. (All other aggregate functions require fields to be specified.)
+- `$sum`, `$avg`, `$max`, `$min`
+- `$card` (cardinality), or the number of unique values in a column

package/index.cjs

@@ -185,7 +185,7 @@ function getCompatibleTypes(value) {
     return "text";
 }
 function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
-  function lookup(string, type) {
+  function lookup2(string, type) {
     if (string.substr(0, 3) === "el$")
       return sql__default["default"]`"${sql.raw(string)}"`;
     return getLookupSql(string, type);
@@ -194,20 +194,20 @@ function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
     const lType = left.substr(0, 3) === "el$" ? "any" : getColumnType(left);
     const rType = getCompatibleTypes(right);
     if (lType === "any" || rType === "any" || rType === lType) {
-      return sql__default["default"]`${lookup(left)} ${sql.raw(op)} ${right}`;
+      return sql__default["default"]`${lookup2(left)} ${sql.raw(op)} ${right}`;
     } else {
-      return sql__default["default"]`(${lookup(left, rType)})::${sql.raw(rType)} ${sql.raw(op)} ${right}`;
+      return sql__default["default"]`(${lookup2(left, rType)})::${sql.raw(rType)} ${sql.raw(op)} ${right}`;
     }
   }
   function getNodeSql(ast) {
     switch (ast[0]) {
       case "$eq":
         if (ast[2] === null)
-          return sql__default["default"]`${lookup(ast[1])} IS NULL`;
+          return sql__default["default"]`${lookup2(ast[1])} IS NULL`;
         return binop("=", ast[1], ast[2]);
       case "$neq":
         if (ast[2] === null)
-          return sql__default["default"]`${lookup(ast[1])} IS NOT NULL`;
+          return sql__default["default"]`${lookup2(ast[1])} IS NOT NULL`;
         return binop("<>", ast[1], ast[2]);
       case "$lt":
         return binop("<", ast[1], ast[2]);
@@ -222,20 +222,20 @@ function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
       case "$ire":
         return binop("~*", ast[1], ast[2]);
       case "$in":
-        return sql__default["default"]`${lookup(ast[1])} IN (${sql.join(ast[2])})`;
+        return sql__default["default"]`${lookup2(ast[1])} IN (${sql.join(ast[2])})`;
       case "$nin":
-        return sql__default["default"]`${lookup(ast[1])} NOT IN (${sql.join(ast[2])})`;
+        return sql__default["default"]`${lookup2(ast[1])} NOT IN (${sql.join(ast[2])})`;
       case "$cts":
-        return sql__default["default"]`${lookup(ast[1])} @> ${ast[2]}`;
+        return sql__default["default"]`${lookup2(ast[1])} @> ${ast[2]}`;
       case "$ctd":
-        return sql__default["default"]`${lookup(ast[1])} <@ ${ast[2]}`;
+        return sql__default["default"]`${lookup2(ast[1])} <@ ${ast[2]}`;
       case "$ovl":
         switch (getColumnType(ast[1])) {
           case "jsonb":
           case "any":
-            return sql__default["default"]`${lookup(ast[1])} ?| ${Array.isArray(ast[2]) ? ast[2] : Object.keys(ast[2])}`;
+            return sql__default["default"]`${lookup2(ast[1])} ?| ${Array.isArray(ast[2]) ? ast[2] : Object.keys(ast[2])}`;
           case "array":
-            return sql__default["default"]`${lookup(ast[1])} && ${ast[2]}`;
+            return sql__default["default"]`${lookup2(ast[1])} && ${ast[2]}`;
           default:
             throw Error("pg.getSql_ovl_unknown_column_type");
         }
@@ -246,11 +246,11 @@ function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
       case "$not":
         return sql__default["default"]`NOT (${getNodeSql(ast[1])})`;
       case "$any":
-        return sql__default["default"]`(SELECT bool_or(${getNodeSql(ast[3])}) FROM UNNEST(${lookup(ast[1])}) ${lookup(ast[2])})`;
+        return sql__default["default"]`(SELECT bool_or(${getNodeSql(ast[3])}) FROM UNNEST(${lookup2(ast[1])}) ${lookup2(ast[2])})`;
       case "$all":
-        return sql__default["default"]`(SELECT bool_and(${getNodeSql(ast[3])}) FROM UNNEST(${lookup(ast[1])}) ${lookup(ast[2])})`;
+        return sql__default["default"]`(SELECT bool_and(${getNodeSql(ast[3])}) FROM UNNEST(${lookup2(ast[1])}) ${lookup2(ast[2])})`;
       case "$has":
-        return sql__default["default"]`(SELECT bool_or(${sql.join(ast[3].map((node) => getNodeSql(node)), `) AND bool_or(`)}) FROM UNNEST(${lookup(ast[1])}) ${lookup(ast[2])})`;
+        return sql__default["default"]`(SELECT bool_or(${sql.join(ast[3].map((node) => getNodeSql(node)), `) AND bool_or(`)}) FROM UNNEST(${lookup2(ast[1])}) ${lookup2(ast[2])})`;
       default:
         throw Error("pg.getSql_unknown_operator: " + ast[0]);
     }
@@ -271,8 +271,40 @@ const getJsonBuildValue = (value) => {
     return sql__default["default"]`${value}::text`;
   return sql__default["default"]`${JSON.stringify(stripAttributes(value))}::jsonb`;
 };
-const getSelectCols = (table) => {
-  return sql__default["default"]`to_jsonb("${sql.raw(table)}")`;
+const lookup = (prop, type) => {
+  const [prefix, ...suffix] = common.encodePath(prop);
+  const op = type === "text" ? sql__default["default"]`#>>` : sql__default["default"]`#>`;
+  return suffix.length ? sql__default["default"]`"${sql.raw(prefix)}" ${op} ${suffix}` : sql__default["default"]`"${sql.raw(prefix)}"`;
+};
+const getType = (prop) => {
+  const [_prefix, ...suffix] = common.encodePath(prop);
+  return suffix.length ? "jsonb" : "any";
+};
+const aggSql = {
+  $sum: (prop) => sql__default["default"]`sum((${lookup(prop)})::numeric)`,
+  $card: (prop) => sql__default["default"]`count(distinct(${lookup(prop)}))`,
+  $avg: (prop) => sql__default["default"]`sum((${lookup(prop)})::numeric)`,
+  $max: (prop) => sql__default["default"]`sum((${lookup(prop)})::numeric)`,
+  $min: (prop) => sql__default["default"]`sum((${lookup(prop)})::numeric)`
+};
+const getSelectCols = (table, projection = null) => {
+  if (!projection)
+    return sql__default["default"]`to_jsonb("${sql.raw(table)}")`;
+  const sqls = [];
+  for (const key in projection) {
+    if (key === "$count") {
+      sqls.push(sql__default["default"]`'$count', count(*)`);
+    } else if (aggSql[key]) {
+      const subSqls = [];
+      for (const prop in projection[key]) {
+        subSqls.push(sql__default["default"]`${prop}::text, ${aggSql[key](prop)}`);
+      }
+      sqls.push(sql__default["default"]`${key}::text, jsonb_build_object(${sql.join(subSqls, ", ")})`);
+    } else {
+      sqls.push(sql__default["default"]`${key}::text, "${sql.raw(key)}"`);
+    }
+  }
+  return sql__default["default"]`jsonb_build_object(${sql.join(sqls, ", ")})`;
 };
 const getInsert = (row, options) => {
   const cols = [];
@@ -322,20 +354,20 @@ const getArgMeta = (key, prefix, idCol) => getJsonBuildObject({
   $ref: sql__default["default"]`jsonb_build_array(${sql.join(prefix.map((k) => sql__default["default"]`${k}::text`))}, "${sql.raw(idCol)}")`,
   $ver: nowTimestamp
 });
+const getAggMeta = (key, $group) => getJsonBuildObject({
+  $key: sql.join([key, getJsonBuildObject({ $group })].filter(Boolean), " || "),
+  $ver: nowTimestamp
+});
 function getArgSql(_c, options) {
   var _d = _c, { $first, $last, $after, $before, $since, $until, $all, $cursor: _ } = _d, rest = __objRest(_d, ["$first", "$last", "$after", "$before", "$since", "$until", "$all", "$cursor"]);
-  const _a = rest, { $order } = _a, filter = __objRest(_a, ["$order"]);
+  const _a = rest, { $order, $group } = _a, filter = __objRest(_a, ["$order", "$group"]);
   const { prefix, idCol } = options;
-  const lookup = (prop, type) => {
-    const [prefix2, ...suffix] = common.encodePath(prop);
-    const op = type === "text" ? sql__default["default"]`#>>` : sql__default["default"]`#>`;
-    return suffix.length ? sql__default["default"]`"${sql.raw(prefix2)}" ${op} ${suffix}` : sql__default["default"]`"${sql.raw(prefix2)}"`;
-  };
-  const getType = (prop) => {
-    const [_prefix, ...suffix] = common.encodePath(prop);
-    return suffix.length ? "jsonb" : "any";
-  };
-  const meta = (key2) => getArgMeta(key2, prefix, idCol);
+  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 groupCols = Array.isArray($group) && $group.length ? $group.map((col) => lookup(col)) : void 0;
+  const group = groupCols ? sql.join(groupCols, ", ") : void 0;
   const hasRangeArg = $before || $after || $since || $until || $first || $last || $all || $order;
   let key;
   const where = [];
@@ -344,7 +376,7 @@ function getArgSql(_c, options) {
     key = sql__default["default"]`${JSON.stringify(filter)}::jsonb`;
   }
   if (!hasRangeArg)
-    return { meta: meta(key), where, limit: 1 };
+    return { meta: meta(key), where, group, limit: 1 };
   if (common.isEmpty(rest)) {
     throw Error("pg_arg.pagination_only_unsupported in " + prefix);
   }
@@ -355,13 +387,14 @@ function getArgSql(_c, options) {
   });
   const orderQuery = $order && getJsonBuildObject({ $order: sql__default["default"]`${JSON.stringify($order)}::jsonb` });
   const cursorQuery = getJsonBuildObject({
-    $cursor: sql__default["default"]`jsonb_build_array(${sql.join(orderCols)})`
+    $cursor: sql__default["default"]`jsonb_build_array(${sql.join(groupCols || orderCols)})`
   });
   key = sql__default["default"]`(${sql.join([key, orderQuery, cursorQuery].filter(Boolean), ` || `)})`;
   return {
     meta: meta(key),
     where,
-    order: sql.join(orderCols.map((col) => sql__default["default"]`${col} ${$last ? sql__default["default"]`DESC` : sql__default["default"]`ASC`}`), `, `),
+    order: $order && sql.join(orderCols.map((col) => sql__default["default"]`${col} ${$last ? sql__default["default"]`DESC` : sql__default["default"]`ASC`}`), `, `),
+    group,
     limit: $first || $last
   };
 }
@@ -395,39 +428,57 @@ function getBoundCond(orderCols, bound, kind) {
   }
 }
 const MAX_LIMIT = 4096;
-function selectByArgs(args, options) {
+function selectByArgs(args, projection, options) {
   const { table } = options;
-  const { where, order, limit, meta } = getArgSql(args, options);
+  const { where, order, group, limit, meta } = getArgSql(args, options);
   const clampedLimit = Math.min(MAX_LIMIT, limit || MAX_LIMIT);
   return sql__default["default"]`
     SELECT
-    ${getSelectCols(table)} || ${meta}
+    ${getSelectCols(table, projection)} || ${meta}
     FROM "${sql.raw(table)}"
     ${where.length ? sql__default["default"]`WHERE ${sql.join(where, ` AND `)}` : sql.empty}
+    ${group ? sql__default["default"]`GROUP BY ${group}` : sql.empty}
     ${order ? sql__default["default"]`ORDER BY ${order}` : sql.empty}
     LIMIT ${clampedLimit}
   `;
 }
-function selectByIds(ids, options) {
+function selectByIds(ids, projection, options) {
   const { table, idCol } = options;
   return sql__default["default"]`
     SELECT
-    ${getSelectCols(table)} || ${getIdMeta(options)}
+    ${getSelectCols(table, projection)} || ${getIdMeta(options)}
     FROM "${sql.raw(table)}"
     WHERE "${sql.raw(idCol)}" IN (${sql.join(ids)})
   `;
 }
-function patch(object, arg, options) {
+function getSingleSql(arg, options) {
   const { table, idCol } = options;
-  const { where, meta } = common.isPlainObject(arg) ? getArgSql(arg, options) : { where: [sql__default["default"]`"${sql.raw(idCol)}" = ${arg}`], meta: getIdMeta(options) };
+  if (!common.isPlainObject(arg)) {
+    return {
+      where: sql__default["default"]`"${sql.raw(idCol)}" = ${arg}`,
+      meta: getIdMeta(options)
+    };
+  }
+  const { where, meta } = getArgSql(arg, options);
   if (!where || !where.length)
     throw Error("pg_write.no_condition");
+  return {
+    where: sql__default["default"]`"${sql.raw(idCol)}" = (
+        SELECT "${sql.raw(idCol)}"
+        FROM "${sql.raw(table)}"
+        WHERE ${sql.join(where, ` AND `)}
+        LIMIT 1
+      )`,
+    meta
+  };
+}
+function patch(object, arg, options) {
+  const { table } = options;
+  const { where, meta } = getSingleSql(arg, options);
   const row = object;
   return sql__default["default"]`
     UPDATE "${sql.raw(table)}" SET ${getUpdates(row, options)}
-    WHERE ${common.isPlainObject(arg) ? sql__default["default"]`"${sql.raw(idCol)}" = (
-            SELECT "${sql.raw(idCol)}" FROM "${sql.raw(table)}"
-            WHERE ${sql.join(where, ` AND `)} LIMIT 1)` : sql.join(where, ` AND `)}
+    WHERE ${where}
     RETURNING (${getSelectCols(table)} || ${meta})`;
 }
 function put(object, arg, options) {
@@ -447,6 +498,14 @@ function put(object, arg, options) {
     ON CONFLICT (${conflictTarget}) DO UPDATE SET (${cols}) = (${vals})
     RETURNING (${getSelectCols(table)} || ${meta})`;
 }
+function del(arg, options) {
+  const { table } = options;
+  const { where } = getSingleSql(arg, options);
+  return sql__default["default"]`
+    DELETE FROM "${sql.raw(table)}"
+    WHERE ${where}
+    RETURNING (${getJsonBuildObject({ $key: arg })})`;
+}
 const log = debug__default["default"]("graffy:pg:db");
 class Db {
   constructor(connection) {
@@ -492,14 +551,14 @@ class Db {
     const promises = [];
     const results = [];
     const { prefix } = tableOptions;
-    const getByArgs = async (args) => {
-      const result = await this.readSql(selectByArgs(args, tableOptions));
+    const getByArgs = async (args, projection) => {
+      const result = await this.readSql(selectByArgs(args, projection, tableOptions));
       const wrappedGraph = common.encodeGraph(common.wrapObject(result, prefix));
       log("getByArgs", wrappedGraph);
       common.merge(results, wrappedGraph);
     };
     const getByIds = async () => {
-      const result = await this.readSql(selectByIds(Object.keys(idQueries), tableOptions));
+      const result = await this.readSql(selectByIds(Object.keys(idQueries), null, tableOptions));
       result.forEach((object) => {
         const wrappedGraph = common.encodeGraph(common.wrapObject(object, prefix));
         log("getByIds", wrappedGraph);
@@ -513,10 +572,12 @@ class Db {
         if (node.prefix) {
           for (const childNode of node.children) {
             const childArgs = common.decodeArgs(childNode);
-            promises.push(getByArgs(__spreadValues(__spreadValues({}, args), childArgs)));
+            const projection = childNode.children ? common.decodeQuery(childNode.children) : true;
+            promises.push(getByArgs(__spreadValues(__spreadValues({}, args), childArgs), projection));
           }
         } else {
-          promises.push(getByArgs(args));
+          const projection = node.children ? common.decodeQuery(node.children) : true;
+          promises.push(getByArgs(args, projection));
         }
       } else {
         idQueries[node.key] = node.children;
@@ -529,15 +590,15 @@ class Db {
     return common.slice(common.finalize(results, common.wrap(query, prefix)), rootQuery).known || [];
   }
   async write(rootChange, tableOptions) {
-    const sqls = [];
-    const addToQuery = (sql2) => sqls.push(sql2);
     const { prefix } = tableOptions;
     const change = common.unwrap(rootChange, prefix);
-    for (const node of change) {
+    const sqls = change.map((node) => {
+      const arg = common.decodeArgs(node);
       if (common.isRange(node)) {
-        throw Error(node.key === node.end ? "pg_write.delete_unsupported" : "pg_write.write_range_unsupported");
+        if (node.key === node.end)
+          return del(arg, tableOptions);
+        throw Error("pg_write.write_range_unsupported");
       }
-      const arg = common.decodeArgs(node);
       const object = common.decodeGraph(node.children);
       if (common.isPlainObject(arg)) {
         common.mergeObject(object, arg);
@@ -547,8 +608,8 @@ class Db {
       if (object.$put && object.$put !== true) {
         throw Error("pg_write.partial_put_unsupported");
       }
-      object.$put ? addToQuery(put(object, arg, tableOptions)) : addToQuery(patch(object, arg, tableOptions));
-    }
+      return object.$put ? put(object, arg, tableOptions) : patch(object, arg, tableOptions);
+    });
     const result = [];
     await Promise.all(sqls.map((sql2) => this.writeSql(sql2).then((object) => {
       common.merge(result, common.encodeGraph(common.wrapObject(object, prefix)));
@@ -557,7 +618,7 @@ class Db {
     return result;
   }
 }
-const pg = ({ table, idCol, verCol, links, connection }) => (store) => {
+const pg = ({ table, idCol, verCol, connection }) => (store) => {
   store.on("read", read);
   store.on("write", write);
   const prefix = store.path;
@@ -565,13 +626,13 @@ const pg = ({ table, idCol, verCol, links, connection }) => (store) => {
     prefix,
     table: table || prefix[prefix.length - 1] || "default",
     idCol: idCol || "id",
-    verCol: verCol || "updatedAt",
-    links: links || {}
+    verCol: verCol || "updatedAt"
   };
   const defaultDb = new Db(connection);
   function read(query, options, next) {
-    const _a = options, { transactionDb = defaultDb } = _a, readOpts = __objRest(_a, ["transactionDb"]);
-    const readPromise = transactionDb.read(query, tableOpts, readOpts);
+    const { pgClient } = options;
+    const db = pgClient ? new Db(pgClient) : defaultDb;
+    const readPromise = db.read(query, tableOpts);
     const remainingQuery = common.remove(query, prefix);
     const nextPromise = next(remainingQuery);
     return Promise.all([readPromise, nextPromise]).then(([readRes, nextRes]) => {
@@ -579,8 +640,9 @@ const pg = ({ table, idCol, verCol, links, connection }) => (store) => {
     });
   }
   function write(change, options, next) {
-    const _a = options, { transactionDb = defaultDb } = _a, writeOpts = __objRest(_a, ["transactionDb"]);
-    const writePromise = transactionDb.write(change, tableOpts, writeOpts);
+    const { pgClient } = options;
+    const db = pgClient ? new Db(pgClient) : defaultDb;
+    const writePromise = db.write(change, tableOpts);
     const remainingChange = common.remove(change, prefix);
     const nextPromise = next(remainingChange);
     return Promise.all([writePromise, nextPromise]).then(([writeRes, nextRes]) => {

package/index.mjs

@@ -26,7 +26,7 @@ var __objRest = (source, exclude) => {
     }
   return target;
 };
-import { isEmpty, encodePath, isPlainObject, unwrap, decodeArgs, slice, finalize, wrap, isRange, decodeGraph, mergeObject, merge, encodeGraph, wrapObject, remove } from "@graffy/common";
+import { isEmpty, encodePath, isPlainObject, unwrap, decodeArgs, decodeQuery, slice, finalize, wrap, isRange, decodeGraph, mergeObject, merge, encodeGraph, wrapObject, remove } from "@graffy/common";
 import { Pool, Client } from "pg";
 import sql, { join, raw, Sql, empty } from "sql-template-tag";
 import debug from "debug";
@@ -177,7 +177,7 @@ function getCompatibleTypes(value) {
     return "text";
 }
 function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
-  function lookup(string, type) {
+  function lookup2(string, type) {
     if (string.substr(0, 3) === "el$")
       return sql`"${raw(string)}"`;
     return getLookupSql(string, type);
@@ -186,20 +186,20 @@ function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
     const lType = left.substr(0, 3) === "el$" ? "any" : getColumnType(left);
     const rType = getCompatibleTypes(right);
     if (lType === "any" || rType === "any" || rType === lType) {
-      return sql`${lookup(left)} ${raw(op)} ${right}`;
+      return sql`${lookup2(left)} ${raw(op)} ${right}`;
     } else {
-      return sql`(${lookup(left, rType)})::${raw(rType)} ${raw(op)} ${right}`;
+      return sql`(${lookup2(left, rType)})::${raw(rType)} ${raw(op)} ${right}`;
     }
   }
   function getNodeSql(ast) {
     switch (ast[0]) {
       case "$eq":
         if (ast[2] === null)
-          return sql`${lookup(ast[1])} IS NULL`;
+          return sql`${lookup2(ast[1])} IS NULL`;
         return binop("=", ast[1], ast[2]);
       case "$neq":
         if (ast[2] === null)
-          return sql`${lookup(ast[1])} IS NOT NULL`;
+          return sql`${lookup2(ast[1])} IS NOT NULL`;
         return binop("<>", ast[1], ast[2]);
       case "$lt":
         return binop("<", ast[1], ast[2]);
@@ -214,20 +214,20 @@ function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
       case "$ire":
         return binop("~*", ast[1], ast[2]);
       case "$in":
-        return sql`${lookup(ast[1])} IN (${join(ast[2])})`;
+        return sql`${lookup2(ast[1])} IN (${join(ast[2])})`;
       case "$nin":
-        return sql`${lookup(ast[1])} NOT IN (${join(ast[2])})`;
+        return sql`${lookup2(ast[1])} NOT IN (${join(ast[2])})`;
       case "$cts":
-        return sql`${lookup(ast[1])} @> ${ast[2]}`;
+        return sql`${lookup2(ast[1])} @> ${ast[2]}`;
       case "$ctd":
-        return sql`${lookup(ast[1])} <@ ${ast[2]}`;
+        return sql`${lookup2(ast[1])} <@ ${ast[2]}`;
       case "$ovl":
         switch (getColumnType(ast[1])) {
           case "jsonb":
           case "any":
-            return sql`${lookup(ast[1])} ?| ${Array.isArray(ast[2]) ? ast[2] : Object.keys(ast[2])}`;
+            return sql`${lookup2(ast[1])} ?| ${Array.isArray(ast[2]) ? ast[2] : Object.keys(ast[2])}`;
           case "array":
-            return sql`${lookup(ast[1])} && ${ast[2]}`;
+            return sql`${lookup2(ast[1])} && ${ast[2]}`;
           default:
             throw Error("pg.getSql_ovl_unknown_column_type");
         }
@@ -238,11 +238,11 @@ function getSql(filter, getLookupSql, getColumnType = defaultColumnType) {
       case "$not":
         return sql`NOT (${getNodeSql(ast[1])})`;
       case "$any":
-        return sql`(SELECT bool_or(${getNodeSql(ast[3])}) FROM UNNEST(${lookup(ast[1])}) ${lookup(ast[2])})`;
+        return sql`(SELECT bool_or(${getNodeSql(ast[3])}) FROM UNNEST(${lookup2(ast[1])}) ${lookup2(ast[2])})`;
       case "$all":
-        return sql`(SELECT bool_and(${getNodeSql(ast[3])}) FROM UNNEST(${lookup(ast[1])}) ${lookup(ast[2])})`;
+        return sql`(SELECT bool_and(${getNodeSql(ast[3])}) FROM UNNEST(${lookup2(ast[1])}) ${lookup2(ast[2])})`;
       case "$has":
-        return sql`(SELECT bool_or(${join(ast[3].map((node) => getNodeSql(node)), `) AND bool_or(`)}) FROM UNNEST(${lookup(ast[1])}) ${lookup(ast[2])})`;
+        return sql`(SELECT bool_or(${join(ast[3].map((node) => getNodeSql(node)), `) AND bool_or(`)}) FROM UNNEST(${lookup2(ast[1])}) ${lookup2(ast[2])})`;
       default:
         throw Error("pg.getSql_unknown_operator: " + ast[0]);
     }
@@ -263,8 +263,40 @@ const getJsonBuildValue = (value) => {
     return sql`${value}::text`;
   return sql`${JSON.stringify(stripAttributes(value))}::jsonb`;
 };
-const getSelectCols = (table) => {
-  return sql`to_jsonb("${raw(table)}")`;
+const lookup = (prop, type) => {
+  const [prefix, ...suffix] = encodePath(prop);
+  const op = type === "text" ? sql`#>>` : sql`#>`;
+  return suffix.length ? sql`"${raw(prefix)}" ${op} ${suffix}` : sql`"${raw(prefix)}"`;
+};
+const getType = (prop) => {
+  const [_prefix, ...suffix] = encodePath(prop);
+  return suffix.length ? "jsonb" : "any";
+};
+const aggSql = {
+  $sum: (prop) => sql`sum((${lookup(prop)})::numeric)`,
+  $card: (prop) => sql`count(distinct(${lookup(prop)}))`,
+  $avg: (prop) => sql`sum((${lookup(prop)})::numeric)`,
+  $max: (prop) => sql`sum((${lookup(prop)})::numeric)`,
+  $min: (prop) => sql`sum((${lookup(prop)})::numeric)`
+};
+const getSelectCols = (table, projection = null) => {
+  if (!projection)
+    return sql`to_jsonb("${raw(table)}")`;
+  const sqls = [];
+  for (const key in projection) {
+    if (key === "$count") {
+      sqls.push(sql`'$count', count(*)`);
+    } else if (aggSql[key]) {
+      const subSqls = [];
+      for (const prop in projection[key]) {
+        subSqls.push(sql`${prop}::text, ${aggSql[key](prop)}`);
+      }
+      sqls.push(sql`${key}::text, jsonb_build_object(${join(subSqls, ", ")})`);
+    } else {
+      sqls.push(sql`${key}::text, "${raw(key)}"`);
+    }
+  }
+  return sql`jsonb_build_object(${join(sqls, ", ")})`;
 };
 const getInsert = (row, options) => {
   const cols = [];
@@ -314,20 +346,20 @@ const getArgMeta = (key, prefix, idCol) => getJsonBuildObject({
   $ref: sql`jsonb_build_array(${join(prefix.map((k) => sql`${k}::text`))}, "${raw(idCol)}")`,
   $ver: nowTimestamp
 });
+const getAggMeta = (key, $group) => getJsonBuildObject({
+  $key: join([key, getJsonBuildObject({ $group })].filter(Boolean), " || "),
+  $ver: nowTimestamp
+});
 function getArgSql(_c, options) {
   var _d = _c, { $first, $last, $after, $before, $since, $until, $all, $cursor: _ } = _d, rest = __objRest(_d, ["$first", "$last", "$after", "$before", "$since", "$until", "$all", "$cursor"]);
-  const _a = rest, { $order } = _a, filter = __objRest(_a, ["$order"]);
+  const _a = rest, { $order, $group } = _a, filter = __objRest(_a, ["$order", "$group"]);
   const { prefix, idCol } = options;
-  const lookup = (prop, type) => {
-    const [prefix2, ...suffix] = encodePath(prop);
-    const op = type === "text" ? sql`#>>` : sql`#>`;
-    return suffix.length ? sql`"${raw(prefix2)}" ${op} ${suffix}` : sql`"${raw(prefix2)}"`;
-  };
-  const getType = (prop) => {
-    const [_prefix, ...suffix] = encodePath(prop);
-    return suffix.length ? "jsonb" : "any";
-  };
-  const meta = (key2) => getArgMeta(key2, prefix, idCol);
+  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 groupCols = Array.isArray($group) && $group.length ? $group.map((col) => lookup(col)) : void 0;
+  const group = groupCols ? join(groupCols, ", ") : void 0;
   const hasRangeArg = $before || $after || $since || $until || $first || $last || $all || $order;
   let key;
   const where = [];
@@ -336,7 +368,7 @@ function getArgSql(_c, options) {
     key = sql`${JSON.stringify(filter)}::jsonb`;
   }
   if (!hasRangeArg)
-    return { meta: meta(key), where, limit: 1 };
+    return { meta: meta(key), where, group, limit: 1 };
   if (isEmpty(rest)) {
     throw Error("pg_arg.pagination_only_unsupported in " + prefix);
   }
@@ -347,13 +379,14 @@ function getArgSql(_c, options) {
   });
   const orderQuery = $order && getJsonBuildObject({ $order: sql`${JSON.stringify($order)}::jsonb` });
   const cursorQuery = getJsonBuildObject({
-    $cursor: sql`jsonb_build_array(${join(orderCols)})`
+    $cursor: sql`jsonb_build_array(${join(groupCols || orderCols)})`
   });
   key = sql`(${join([key, orderQuery, cursorQuery].filter(Boolean), ` || `)})`;
   return {
     meta: meta(key),
     where,
-    order: join(orderCols.map((col) => sql`${col} ${$last ? sql`DESC` : sql`ASC`}`), `, `),
+    order: $order && join(orderCols.map((col) => sql`${col} ${$last ? sql`DESC` : sql`ASC`}`), `, `),
+    group,
     limit: $first || $last
   };
 }
@@ -387,39 +420,57 @@ function getBoundCond(orderCols, bound, kind) {
   }
 }
 const MAX_LIMIT = 4096;
-function selectByArgs(args, options) {
+function selectByArgs(args, projection, options) {
   const { table } = options;
-  const { where, order, limit, meta } = getArgSql(args, options);
+  const { where, order, group, limit, meta } = getArgSql(args, options);
   const clampedLimit = Math.min(MAX_LIMIT, limit || MAX_LIMIT);
   return sql`
     SELECT
-    ${getSelectCols(table)} || ${meta}
+    ${getSelectCols(table, projection)} || ${meta}
     FROM "${raw(table)}"
     ${where.length ? sql`WHERE ${join(where, ` AND `)}` : empty}
+    ${group ? sql`GROUP BY ${group}` : empty}
     ${order ? sql`ORDER BY ${order}` : empty}
     LIMIT ${clampedLimit}
   `;
 }
-function selectByIds(ids, options) {
+function selectByIds(ids, projection, options) {
   const { table, idCol } = options;
   return sql`
     SELECT
-    ${getSelectCols(table)} || ${getIdMeta(options)}
+    ${getSelectCols(table, projection)} || ${getIdMeta(options)}
     FROM "${raw(table)}"
     WHERE "${raw(idCol)}" IN (${join(ids)})
   `;
 }
-function patch(object, arg, options) {
+function getSingleSql(arg, options) {
   const { table, idCol } = options;
-  const { where, meta } = isPlainObject(arg) ? getArgSql(arg, options) : { where: [sql`"${raw(idCol)}" = ${arg}`], meta: getIdMeta(options) };
+  if (!isPlainObject(arg)) {
+    return {
+      where: sql`"${raw(idCol)}" = ${arg}`,
+      meta: getIdMeta(options)
+    };
+  }
+  const { where, meta } = getArgSql(arg, options);
   if (!where || !where.length)
     throw Error("pg_write.no_condition");
+  return {
+    where: sql`"${raw(idCol)}" = (
+        SELECT "${raw(idCol)}"
+        FROM "${raw(table)}"
+        WHERE ${join(where, ` AND `)}
+        LIMIT 1
+      )`,
+    meta
+  };
+}
+function patch(object, arg, options) {
+  const { table } = options;
+  const { where, meta } = getSingleSql(arg, options);
   const row = object;
   return sql`
     UPDATE "${raw(table)}" SET ${getUpdates(row, options)}
-    WHERE ${isPlainObject(arg) ? sql`"${raw(idCol)}" = (
-            SELECT "${raw(idCol)}" FROM "${raw(table)}"
-            WHERE ${join(where, ` AND `)} LIMIT 1)` : join(where, ` AND `)}
+    WHERE ${where}
     RETURNING (${getSelectCols(table)} || ${meta})`;
 }
 function put(object, arg, options) {
@@ -439,6 +490,14 @@ function put(object, arg, options) {
     ON CONFLICT (${conflictTarget}) DO UPDATE SET (${cols}) = (${vals})
     RETURNING (${getSelectCols(table)} || ${meta})`;
 }
+function del(arg, options) {
+  const { table } = options;
+  const { where } = getSingleSql(arg, options);
+  return sql`
+    DELETE FROM "${raw(table)}"
+    WHERE ${where}
+    RETURNING (${getJsonBuildObject({ $key: arg })})`;
+}
 const log = debug("graffy:pg:db");
 class Db {
   constructor(connection) {
@@ -484,14 +543,14 @@ class Db {
     const promises = [];
     const results = [];
     const { prefix } = tableOptions;
-    const getByArgs = async (args) => {
-      const result = await this.readSql(selectByArgs(args, tableOptions));
+    const getByArgs = async (args, projection) => {
+      const result = await this.readSql(selectByArgs(args, projection, tableOptions));
       const wrappedGraph = encodeGraph(wrapObject(result, prefix));
       log("getByArgs", wrappedGraph);
       merge(results, wrappedGraph);
     };
     const getByIds = async () => {
-      const result = await this.readSql(selectByIds(Object.keys(idQueries), tableOptions));
+      const result = await this.readSql(selectByIds(Object.keys(idQueries), null, tableOptions));
       result.forEach((object) => {
         const wrappedGraph = encodeGraph(wrapObject(object, prefix));
         log("getByIds", wrappedGraph);
@@ -505,10 +564,12 @@ class Db {
         if (node.prefix) {
           for (const childNode of node.children) {
             const childArgs = decodeArgs(childNode);
-            promises.push(getByArgs(__spreadValues(__spreadValues({}, args), childArgs)));
+            const projection = childNode.children ? decodeQuery(childNode.children) : true;
+            promises.push(getByArgs(__spreadValues(__spreadValues({}, args), childArgs), projection));
           }
         } else {
-          promises.push(getByArgs(args));
+          const projection = node.children ? decodeQuery(node.children) : true;
+          promises.push(getByArgs(args, projection));
         }
       } else {
         idQueries[node.key] = node.children;
@@ -521,15 +582,15 @@ class Db {
     return slice(finalize(results, wrap(query, prefix)), rootQuery).known || [];
   }
   async write(rootChange, tableOptions) {
-    const sqls = [];
-    const addToQuery = (sql2) => sqls.push(sql2);
     const { prefix } = tableOptions;
     const change = unwrap(rootChange, prefix);
-    for (const node of change) {
+    const sqls = change.map((node) => {
+      const arg = decodeArgs(node);
       if (isRange(node)) {
-        throw Error(node.key === node.end ? "pg_write.delete_unsupported" : "pg_write.write_range_unsupported");
+        if (node.key === node.end)
+          return del(arg, tableOptions);
+        throw Error("pg_write.write_range_unsupported");
       }
-      const arg = decodeArgs(node);
       const object = decodeGraph(node.children);
       if (isPlainObject(arg)) {
         mergeObject(object, arg);
@@ -539,8 +600,8 @@ class Db {
       if (object.$put && object.$put !== true) {
         throw Error("pg_write.partial_put_unsupported");
       }
-      object.$put ? addToQuery(put(object, arg, tableOptions)) : addToQuery(patch(object, arg, tableOptions));
-    }
+      return object.$put ? put(object, arg, tableOptions) : patch(object, arg, tableOptions);
+    });
     const result = [];
     await Promise.all(sqls.map((sql2) => this.writeSql(sql2).then((object) => {
       merge(result, encodeGraph(wrapObject(object, prefix)));
@@ -549,7 +610,7 @@ class Db {
     return result;
   }
 }
-const pg = ({ table, idCol, verCol, links, connection }) => (store) => {
+const pg = ({ table, idCol, verCol, connection }) => (store) => {
   store.on("read", read);
   store.on("write", write);
   const prefix = store.path;
@@ -557,13 +618,13 @@ const pg = ({ table, idCol, verCol, links, connection }) => (store) => {
     prefix,
     table: table || prefix[prefix.length - 1] || "default",
     idCol: idCol || "id",
-    verCol: verCol || "updatedAt",
-    links: links || {}
+    verCol: verCol || "updatedAt"
   };
   const defaultDb = new Db(connection);
   function read(query, options, next) {
-    const _a = options, { transactionDb = defaultDb } = _a, readOpts = __objRest(_a, ["transactionDb"]);
-    const readPromise = transactionDb.read(query, tableOpts, readOpts);
+    const { pgClient } = options;
+    const db = pgClient ? new Db(pgClient) : defaultDb;
+    const readPromise = db.read(query, tableOpts);
     const remainingQuery = remove(query, prefix);
     const nextPromise = next(remainingQuery);
     return Promise.all([readPromise, nextPromise]).then(([readRes, nextRes]) => {
@@ -571,8 +632,9 @@ const pg = ({ table, idCol, verCol, links, connection }) => (store) => {
     });
   }
   function write(change, options, next) {
-    const _a = options, { transactionDb = defaultDb } = _a, writeOpts = __objRest(_a, ["transactionDb"]);
-    const writePromise = transactionDb.write(change, tableOpts, writeOpts);
+    const { pgClient } = options;
+    const db = pgClient ? new Db(pgClient) : defaultDb;
+    const writePromise = db.write(change, tableOpts);
     const remainingChange = remove(change, prefix);
     const nextPromise = next(remainingChange);
     return Promise.all([writePromise, nextPromise]).then(([writeRes, nextRes]) => {

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.11",
+  "version": "0.15.13-alpha.1",
   "main": "./index.cjs",
   "exports": {
     "import": "./index.mjs",
@@ -16,9 +16,11 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@graffy/common": "0.15.11",
-    "pg": "^8.7.1",
+    "@graffy/common": "0.15.13-alpha.1",
     "debug": "^4.3.2",
     "sql-template-tag": "^4.0.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
   }
 }

package/types/index.d.ts

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

package/types/sql/clauses.d.ts

@@ -1,6 +1,8 @@
 export const nowTimestamp: Sql;
 export function getJsonBuildObject(variadic: any): Sql;
-export function getSelectCols(table: any): Sql;
+export function lookup(prop: any, type: any): Sql;
+export function getType(prop: any): "any" | "jsonb";
+export function getSelectCols(table: any, projection?: any): Sql;
 export function getInsert(row: any, options: any): {
     cols: Sql;
     vals: Sql;

package/types/sql/getArgSql.d.ts

@@ -5,12 +5,13 @@
   @param {object} options
 
   @typedef { import('sql-template-tag').Sql } Sql
-  @return {{ meta: Sql, where: Sql[], order?: Sql, limit: number }}
+  @return {{ meta: Sql, where: Sql[], order?: Sql, group?: Sql, limit: number }}
 */
 export default function getArgSql({ $first, $last, $after, $before, $since, $until, $all, $cursor: _, ...rest }: object, options: object): {
     meta: Sql;
     where: Sql[];
     order?: Sql;
+    group?: Sql;
     limit: number;
 };
 /**

package/types/sql/getMeta.d.ts

@@ -2,3 +2,4 @@ export function getIdMeta({ idCol }: {
     idCol: 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;

package/types/sql/select.d.ts

@@ -1,2 +1,2 @@
-export function selectByArgs(args: any, options: any): import("sql-template-tag").Sql;
-export function selectByIds(ids: any, options: any): import("sql-template-tag").Sql;
+export function selectByArgs(args: any, projection: any, options: any): import("sql-template-tag").Sql;
+export function selectByIds(ids: any, projection: any, options: any): import("sql-template-tag").Sql;

package/types/sql/upsert.d.ts

@@ -1,2 +1,3 @@
 export function patch(object: any, arg: any, options: any): import("sql-template-tag").Sql;
 export function put(object: any, arg: any, options: any): import("sql-template-tag").Sql;
+export function del(arg: any, options: any): import("sql-template-tag").Sql;