graphile-pg-aggregates 1.1.0

package/AggregateSpecsPlugin.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgAggregatesSpecsPlugin = void 0;
+const EXPORTABLE_1 = require("./EXPORTABLE");
+const interfaces_1 = require("./interfaces");
+const version = '1.0.0';
+const isNumberLike = (codec) => !!codec.extensions?.isNumberLike;
+const isIntervalLike = (codec) => !!codec.extensions?.isIntervalLike;
+const isIntervalLikeOrNumberLike = (0, EXPORTABLE_1.EXPORTABLE)((isIntervalLike, isNumberLike) => (codec) => isIntervalLike(codec) || isNumberLike(codec), [isIntervalLike, isNumberLike]);
+exports.PgAggregatesSpecsPlugin = {
+    name: 'PgAggregatesSpecsPlugin',
+    description: 'Created the default (extensible) aggregate specs and group-by specs used throughout this preset.',
+    version,
+    provides: ['aggregates'],
+    after: ['PgBasicsPlugin'],
+    gather: {
+        hooks: {
+            pgCodecs_PgCodec(_info, event) {
+                const { pgType, pgCodec } = event;
+                const isReg = pgType.getNamespace()?.nspname === 'pg_catalog' &&
+                    pgType.typname.startsWith('reg');
+                const isCatN = !isReg && pgType.typcategory === 'N';
+                const isInterval = !isReg && pgType._id === interfaces_1.INTERVAL_OID;
+                if (isCatN || isInterval) {
+                    if (!pgCodec.extensions) {
+                        pgCodec.extensions = Object.create(null);
+                    }
+                }
+                if (isCatN) {
+                    pgCodec.extensions.isNumberLike = true;
+                }
+                if (isInterval) {
+                    pgCodec.extensions.isIntervalLike = true;
+                }
+            }
+        }
+    },
+    schema: {
+        hooks: {
+            build(build) {
+                if (!build.dataplanPg || !build.sql) {
+                    throw new Error(`PgBasicsPlugin must be loaded first`);
+                }
+                const { sql, dataplanPg: { TYPES }, EXPORTABLE } = build;
+                /** Maps from the data type of the attribute to the data type of the sum aggregate */
+                /** BigFloat is our fallback type; it should be valid for almost all numeric types */
+                const convertWithMapAndFallback = (dataTypeToAggregateTypeMap, fallback) => {
+                    return EXPORTABLE((dataTypeToAggregateTypeMap, fallback) => (codec) => {
+                        const oid = codec.extensions?.oid;
+                        const targetType = (oid ? dataTypeToAggregateTypeMap[oid] : null) ?? fallback;
+                        return targetType;
+                    }, [dataTypeToAggregateTypeMap, fallback]);
+                };
+                const pgAggregateSpecs = [
+                    {
+                        id: 'sum',
+                        humanLabel: 'sum',
+                        HumanLabel: 'Sum',
+                        isSuitableType: isIntervalLikeOrNumberLike,
+                        // I've wrapped it in `coalesce` so that it cannot be null
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `coalesce(sum(${sqlFrag}), '0')`, [sql]),
+                        isNonNull: true,
+                        // A SUM(...) often ends up significantly larger than any individual
+                        // value; see
+                        // https://www.postgresql.org/docs/current/functions-aggregate.html for
+                        // how the sum aggregate changes result type.
+                        pgTypeCodecModifier: convertWithMapAndFallback({
+                            // TODO: this should use codecs rather than OIDs
+                            [interfaces_1.INT2_OID]: TYPES.bigint, // smallint -> bigint
+                            [interfaces_1.INT4_OID]: TYPES.bigint, // integer -> bigint
+                            [interfaces_1.BIGINT_OID]: TYPES.numeric, // bigint -> numeric
+                            [interfaces_1.FLOAT4_OID]: TYPES.float4, // real -> real
+                            [interfaces_1.FLOAT8_OID]: TYPES.float, // double precision -> double precision
+                            [interfaces_1.INTERVAL_OID]: TYPES.interval, // interval -> interval
+                            [interfaces_1.MONEY_OID]: TYPES.money // money -> money
+                        }, TYPES.numeric /* numeric */)
+                    },
+                    {
+                        id: 'distinctCount',
+                        humanLabel: 'distinct count',
+                        HumanLabel: 'Distinct count',
+                        isSuitableType: () => true,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `count(distinct ${sqlFrag})`, [sql]),
+                        pgTypeCodecModifier: convertWithMapAndFallback({}, TYPES.bigint /* always use bigint */)
+                    },
+                    {
+                        id: 'min',
+                        humanLabel: 'minimum',
+                        HumanLabel: 'Minimum',
+                        isSuitableType: isIntervalLikeOrNumberLike,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `min(${sqlFrag})`, [sql])
+                    },
+                    {
+                        id: 'max',
+                        humanLabel: 'maximum',
+                        HumanLabel: 'Maximum',
+                        isSuitableType: isIntervalLikeOrNumberLike,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `max(${sqlFrag})`, [sql])
+                    },
+                    {
+                        id: 'average',
+                        humanLabel: 'mean average',
+                        HumanLabel: 'Mean average',
+                        isSuitableType: isIntervalLikeOrNumberLike,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `avg(${sqlFrag})`, [sql]),
+                        // An AVG(...) ends up more precise than any individual value; see
+                        // https://www.postgresql.org/docs/current/functions-aggregate.html for
+                        // how the avg aggregate changes result type.
+                        pgTypeCodecModifier: convertWithMapAndFallback({
+                            [interfaces_1.INT2_OID]: TYPES.numeric, // smallint -> numeric
+                            [interfaces_1.INT4_OID]: TYPES.numeric, // integer -> numeric
+                            [interfaces_1.BIGINT_OID]: TYPES.numeric, // bigint -> numeric
+                            [interfaces_1.NUMERIC_OID]: TYPES.numeric, // numeric -> numeric
+                            [interfaces_1.FLOAT4_OID]: TYPES.float, // real -> double precision
+                            [interfaces_1.FLOAT8_OID]: TYPES.float, // double precision -> double precision
+                            [interfaces_1.INTERVAL_OID]: TYPES.interval // interval -> interval
+                        }, TYPES.numeric /* numeric */)
+                    },
+                    {
+                        id: 'stddevSample',
+                        humanLabel: 'sample standard deviation',
+                        HumanLabel: 'Sample standard deviation',
+                        isSuitableType: isNumberLike,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `stddev_samp(${sqlFrag})`, [sql]),
+                        // See https://www.postgresql.org/docs/current/functions-aggregate.html
+                        // for how this aggregate changes result type.
+                        pgTypeCodecModifier: convertWithMapAndFallback({
+                            [interfaces_1.FLOAT4_OID]: TYPES.float, // real -> double precision
+                            [interfaces_1.FLOAT8_OID]: TYPES.float // double precision -> double precision
+                        }, TYPES.numeric /* numeric */)
+                    },
+                    {
+                        id: 'stddevPopulation',
+                        humanLabel: 'population standard deviation',
+                        HumanLabel: 'Population standard deviation',
+                        isSuitableType: isNumberLike,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `stddev_pop(${sqlFrag})`, [sql]),
+                        // See https://www.postgresql.org/docs/current/functions-aggregate.html
+                        // for how this aggregate changes result type.
+                        pgTypeCodecModifier: convertWithMapAndFallback({
+                            [interfaces_1.FLOAT4_OID]: TYPES.float, // real -> double precision
+                            [interfaces_1.FLOAT8_OID]: TYPES.float // double precision -> double precision
+                        }, TYPES.numeric /* numeric */)
+                    },
+                    {
+                        id: 'varianceSample',
+                        humanLabel: 'sample variance',
+                        HumanLabel: 'Sample variance',
+                        isSuitableType: isNumberLike,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `var_samp(${sqlFrag})`, [sql]),
+                        // See https://www.postgresql.org/docs/current/functions-aggregate.html
+                        // for how this aggregate changes result type.
+                        pgTypeCodecModifier: convertWithMapAndFallback({
+                            [interfaces_1.FLOAT4_OID]: TYPES.float, // real -> double precision
+                            [interfaces_1.FLOAT8_OID]: TYPES.float // double precision -> double precision
+                        }, TYPES.numeric /* numeric */)
+                    },
+                    {
+                        id: 'variancePopulation',
+                        humanLabel: 'population variance',
+                        HumanLabel: 'Population variance',
+                        isSuitableType: isNumberLike,
+                        sqlAggregateWrap: EXPORTABLE((sql) => (sqlFrag) => sql `var_pop(${sqlFrag})`, [sql]),
+                        // See https://www.postgresql.org/docs/current/functions-aggregate.html
+                        // for how this aggregate changes result type.
+                        pgTypeCodecModifier: convertWithMapAndFallback({
+                            [interfaces_1.FLOAT4_OID]: TYPES.float, // real -> double precision
+                            [interfaces_1.FLOAT8_OID]: TYPES.float // double precision -> double precision
+                        }, TYPES.numeric /* numeric */)
+                    }
+                ];
+                const pgAggregateGroupBySpecs = [
+                    {
+                        id: 'truncated-to-hour',
+                        isSuitableType: EXPORTABLE((TYPES) => (codec) => codec === TYPES.timestamp || codec === TYPES.timestamptz, [TYPES]),
+                        sqlWrap: EXPORTABLE((sql) => (sqlFrag) => sql `date_trunc('hour', ${sqlFrag})`, [sql]),
+                        sqlWrapCodec(codec) {
+                            return codec;
+                        }
+                    },
+                    {
+                        id: 'truncated-to-day',
+                        isSuitableType: EXPORTABLE((TYPES) => (codec) => codec === TYPES.timestamp || codec === TYPES.timestamptz, [TYPES]),
+                        sqlWrap: EXPORTABLE((sql) => (sqlFrag) => sql `date_trunc('day', ${sqlFrag})`, [sql]),
+                        sqlWrapCodec(codec) {
+                            return codec;
+                        }
+                    }
+                ];
+                return build.extend(build, {
+                    pgAggregateSpecs,
+                    pgAggregateGroupBySpecs
+                }, 'Adding aggregate specs to build');
+            },
+            finalize(schema, build) {
+                build.pgAggregateSpecs.forEach((spec) => {
+                    build.exportNameHint(spec, `pgAggregateSpec_${spec.id.replace(/-/g, '_')}`);
+                });
+                build.pgAggregateGroupBySpecs.forEach((spec) => {
+                    build.exportNameHint(spec, `pgAggregateGroupBySpec_${spec.id.replace(/-/g, '_')}`);
+                });
+                return schema;
+            }
+        }
+    }
+};

package/AggregatesSmartTagsPlugin.d.ts

@@ -0,0 +1,8 @@
+declare global {
+    namespace GraphileConfig {
+        interface GatherHelpers {
+            pgV4AggregatesSmartTags: Record<string, never>;
+        }
+    }
+}
+export declare const PgAggregatesSmartTagsPlugin: GraphileConfig.Plugin;

package/AggregatesSmartTagsPlugin.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgAggregatesSmartTagsPlugin = void 0;
+const version = '1.0.0';
+const EMPTY_OBJECT = Object.freeze({});
+exports.PgAggregatesSmartTagsPlugin = {
+    name: 'PgAggregatesSmartTagsPlugin',
+    description: 'For compatibility with PostGraphile v4 schemas, this plugin attempts to convert `@aggregates` V4 smart tags to V5 behaviors',
+    version,
+    before: [
+        'PgAggregatesAddAggregateTypesPlugin',
+        'PgAggregatesFilterRelationalAggregatesPlugin',
+        'PgAggregatesOrderByAggregatesPlugin'
+    ],
+    provides: ['smart-tags'],
+    gather: {
+        namespace: 'pgV4AggregatesSmartTags',
+        initialCache() {
+            return EMPTY_OBJECT;
+        },
+        initialState() {
+            return EMPTY_OBJECT;
+        },
+        helpers: {},
+        hooks: {
+            // Run in the 'introspection' phase before anything uses the tags
+            pgIntrospection_introspection(info, event) {
+                for (const pgClass of event.introspection.classes) {
+                    processTags(pgClass.getTags());
+                }
+            }
+        }
+    }
+};
+function processTags(tags) {
+    switch (tags?.aggregates) {
+        case 'on':
+            addBehaviorToTags(tags, '+aggregates +aggregates:filterBy +aggregates:orderBy +aggregate +aggregate:filterBy +aggregate:orderBy');
+            break;
+        case 'off':
+            addBehaviorToTags(tags, '-aggregates -aggregates:filterBy -aggregates:orderBy -aggregate -aggregate:filterBy -aggregate:orderBy');
+            break;
+    }
+}
+function addBehaviorToTags(tags, behavior, prepend = false) {
+    if (Array.isArray(tags.behavior)) {
+        if (prepend) {
+            tags.behavior = [behavior, ...tags.behavior];
+        }
+        else {
+            tags.behavior = [...tags.behavior, behavior];
+        }
+    }
+    else if (typeof tags.behavior === 'string') {
+        tags.behavior = prepend
+            ? [behavior, tags.behavior]
+            : [tags.behavior, behavior];
+    }
+    else if (!tags.behavior) {
+        tags.behavior = [behavior];
+    }
+    else {
+        throw new Error(`Did not understand tags.behavior - it wasn't an array or a string`);
+    }
+}

package/EXPORTABLE.d.ts

@@ -0,0 +1 @@
+export declare function EXPORTABLE<T, TScope extends any[]>(factory: (...args: TScope) => T, args: [...TScope], nameHint?: string): T;

package/EXPORTABLE.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPORTABLE = EXPORTABLE;
+function EXPORTABLE(factory, args, nameHint) {
+    const fn = factory(...args);
+    if (((typeof fn === 'object' && fn !== null) || typeof fn === 'function') &&
+        !('$exporter$factory' in fn)) {
+        Object.defineProperties(fn, {
+            $exporter$args: { value: args },
+            $exporter$factory: { value: factory },
+            $exporter$name: { writable: true, value: nameHint }
+        });
+    }
+    return fn;
+}

package/FilterRelationalAggregatesPlugin.d.ts

@@ -0,0 +1,74 @@
+import type { PgCodec, PgConditionCapableParent, PgWhereConditionSpec, sql } from '@dataplan/pg';
+import type { Modifier } from 'grafast';
+import type { AggregateSpec } from './interfaces';
+type PgSQL = typeof sql;
+type SQL = ReturnType<PgSQL>;
+declare global {
+    namespace DataplanPg {
+        interface PgConditionExtensions {
+            pgFilterAttribute?: {
+                fieldName?: string;
+                codec: PgCodec;
+                expression?: SQL;
+            };
+        }
+    }
+    namespace GraphileBuild {
+        interface Build {
+            PgAggregateCondition: PgAggregateConditionClass;
+            PgAggregateConditionExpression: PgAggregateConditionExpressionClass;
+        }
+        interface BehaviorStrings {
+            'resource:aggregates:filterBy': true;
+            'aggregates:filterBy': true;
+            'aggregate:filterBy': true;
+            'sum:resource:aggregates:filterBy': true;
+            'distinctCount:resource:aggregates:filterBy': true;
+            'min:resource:aggregates:filterBy': true;
+            'max:resource:aggregates:filterBy': true;
+            'average:resource:aggregates:filterBy': true;
+            'stddevSample:resource:aggregates:filterBy': true;
+            'stddevPopulation:resource:aggregates:filterBy': true;
+            'varianceSample:resource:aggregates:filterBy': true;
+            'variancePopulation:resource:aggregates:filterBy': true;
+            'sum:attribute:aggregate:filterBy': true;
+            'distinctCount:attribute:aggregate:filterBy': true;
+            'min:attribute:aggregate:filterBy': true;
+            'max:attribute:aggregate:filterBy': true;
+            'average:attribute:aggregate:filterBy': true;
+            'stddevSample:attribute:aggregate:filterBy': true;
+            'stddevPopulation:attribute:aggregate:filterBy': true;
+            'varianceSample:attribute:aggregate:filterBy': true;
+            'variancePopulation:attribute:aggregate:filterBy': true;
+        }
+    }
+}
+export declare const Plugin: GraphileConfig.Plugin;
+export { Plugin as PgAggregatesFilterRelationalAggregatesPlugin };
+interface PgAggregateCondition<TParentStep extends PgConditionCapableParent> extends Modifier<TParentStep> {
+    sql: PgSQL;
+    tableExpression: SQL;
+    alias: SQL;
+    conditions: PgWhereConditionSpec<any>[];
+    expressions: SQL[];
+    where(condition: PgWhereConditionSpec<any>): void;
+    expression(expression: SQL): void;
+    forAggregate(spec: AggregateSpec): PgAggregateConditionExpression;
+    apply(): void;
+}
+interface PgAggregateConditionClass {
+    new <TParentStep extends PgConditionCapableParent>($parent: TParentStep, options: {
+        sql: PgSQL;
+        tableExpression: SQL;
+        alias?: string;
+    }, pgWhereConditionSpecListToSQL: GraphileBuild.Build['dataplanPg']['pgWhereConditionSpecListToSQL']): PgAggregateCondition<TParentStep>;
+}
+interface PgAggregateConditionExpression extends Modifier<PgAggregateCondition<any>> {
+    alias: SQL;
+    conditions: PgWhereConditionSpec<any>[];
+    where(condition: PgWhereConditionSpec<any>): void;
+    apply(): void;
+}
+interface PgAggregateConditionExpressionClass {
+    new ($parent: PgAggregateCondition<any>, spec: AggregateSpec, pgWhereConditionSpecListToSQL: GraphileBuild.Build['dataplanPg']['pgWhereConditionSpecListToSQL']): PgAggregateConditionExpression;
+}