@appweaver/data 0.0.0-stage → 2.0.0

package/resource/utils/aggregate-util.d.ts

@@ -0,0 +1,113 @@
+import { AggregateSelect, AggregateValue, ResourceClient, ResourceModel } from '@appweaver/common';
+/** The kind of value an aggregatable field holds. */
+export type AggregateFieldType = 'numeric' | 'date';
+/**
+ * The operations a selection is resolved by: the arguments of a single database aggregation, and the fields read off
+ * the earliest and the latest record of the aggregated range.
+ */
+export type AggregationOperations = {
+    /** The Prisma aggregation arguments, keyed by the prefixed operator name */
+    aggregate: Record<string, any>;
+    /** The fields whose value is read off the earliest record of the range */
+    first: string[];
+    /** The fields whose value is read off the latest record of the range */
+    last: string[];
+};
+/** A single aggregation period, labeled with the median date of its range. */
+export interface AggregationRange {
+    from: Date;
+    to: Date;
+    median: Date;
+}
+/** The resolved aggregation date range together with its periods. */
+export interface AggregationPeriods {
+    fromDate: Date;
+    toDate: Date;
+    ranges: AggregationRange[];
+}
+/**
+ * Resolves an aggregation date range from its ISO string bounds and splits it into equally sized periods.
+ *
+ * @param {string} [from] - The ISO date string of the range start. Defaults to seven days before the range end.
+ * @param {string} [to] - The ISO date string of the range end. Defaults to the current date and time.
+ * @param {number} [step] - The size of a single period in units of the automatically selected time unit. If not
+ * provided, one unit is used and the unit is derived from the range length.
+ * @param {boolean} [safeIncrement=true] - Whether the period increments use the derived time unit and stay consistent
+ * across daylight saving time changes. When false, the step is interpreted in seconds.
+ * @return {AggregationPeriods} The resolved range bounds and one range per period, each labeled with its median date.
+ */
+export declare function buildAggregationPeriods(from?: string, to?: string, step?: number, safeIncrement?: boolean): AggregationPeriods;
+/**
+ * Maps an aggregation selection to the operations that resolve it, splitting the operators the database aggregates in
+ * a single query from the `first` and `last` operators, which read the boundary records of the range instead. Every
+ * field is validated against the model it is aggregated on, and every operator against the kind of value its field
+ * holds, since only the numeric fields can be summed and averaged.
+ *
+ * @param {AggregateSelect<Object>} select - The operations to perform per field, with the operators of a field nested
+ * inside it. The operators set to false are left out.
+ * @param {string} resourceName - The name of the model the selection is aggregated on.
+ * @return {AggregationOperations} The Prisma aggregation arguments, keyed by the prefixed operator name with the
+ * selected fields nested inside, together with the fields read off the earliest and the latest record of the range.
+ * The arguments always count the records of the range when a boundary field was selected, so the boundary queries can
+ * be skipped for the empty ranges.
+ * @throws {ResourceError} `RESOURCE_INVALID_AGGREGATE` if the selection is not an object, selects no operation at all, names a field the model
+ * cannot aggregate, or applies an operator the kind of value of its field does not support.
+ */
+export declare function mapAggregationSelect<T>(select: AggregateSelect<T>, resourceName: string): AggregationOperations;
+/**
+ * Maps a Prisma aggregation result back to the response format by swapping the operator and field nesting, so a
+ * `{ _count: { views: 3 } }` result becomes the `{ views: { count: 3 } }` response value. The boundary record values
+ * are mapped the same way when they are merged into the result under their own `_first` and `_last` keys.
+ *
+ * @param {Object} result - The Prisma aggregation result, keyed by the prefixed operator name with the aggregated
+ * fields nested inside.
+ * @return {AggregateValue<Object>} The aggregated values keyed by field name, with the operator results nested inside.
+ * The record count of the range is left out, since it counts no field of its own.
+ */
+export declare function mapAggregationResult<T>(result: Record<string, Record<string, any>>): AggregateValue<T>;
+/**
+ * Reads the `first` and `last` values of an aggregated range off its boundary records. The earliest and the latest
+ * record of the range are looked up by the same date field the range is sliced by, with the record id breaking the
+ * ties, and only the selected fields are read off them. The values of an empty range are resolved to null without
+ * querying for them, so a range the aggregation already counted as empty costs nothing.
+ *
+ * @param {ResourceClient} client - The model client the boundary records are read with, which is the transaction
+ * client of the aggregation.
+ * @param {Object} where - The database query of the aggregated range, applied unchanged to the boundary lookups.
+ * @param {string} dateField - The date field the range is sliced by, which the boundary records are ordered by.
+ * @param {AggregationOperations} operations - The operations holding the fields to read off each boundary record.
+ * @param {number} [recordCount] - The number of records in the range, used to skip the lookups of an empty range. When
+ * omitted, the lookups are always performed.
+ * @return {Promise<Object>} The boundary values keyed by the prefixed operator name (`_first` and `_last`) with the
+ * read fields nested inside, ready to be merged into the aggregation result of the range. Empty when no boundary field
+ * was selected.
+ */
+export declare function readAggregationBoundaries(client: ResourceClient, where: any, dateField: string, operations: AggregationOperations, recordCount?: number): Promise<Record<string, any>>;
+/**
+ * Reads the record count a Prisma aggregation result holds for its range, as counted by the `_all` selection that
+ * {@link mapAggregationSelect} adds whenever a boundary field is selected.
+ *
+ * @param {Object} result - The Prisma aggregation result to read the count off.
+ * @return {number|undefined} The number of records in the range, or undefined when the result does not count them.
+ */
+export declare function aggregationRecordCount(result: Record<string, any>): number | undefined;
+/**
+ * Validates the date field the aggregated range is applied on against the model it is aggregated on.
+ *
+ * @param {string} dateField - The name of the date field to validate.
+ * @param {string} resourceName - The name of the model the range is applied on.
+ * @return {string} The validated date field name.
+ * @throws {ResourceError} `RESOURCE_INVALID_AGGREGATE` if the model has no date field under that name.
+ */
+export declare function checkAggregationDateField(dateField: string, resourceName: string): string;
+/**
+ * Lists the aggregatable fields of a resource model together with the kind of value they hold. The id is aggregatable
+ * when it is numeric, the audit fields follow the audit configuration of the model, and the scalars are aggregatable
+ * when they hold a single numeric or date value and are not hidden. The virtual fields are never aggregatable, since
+ * they have no column of their own.
+ *
+ * @param {ResourceModel} model - The resource model whose fields are listed.
+ * @return {Array} The name and kind (`numeric` or `date`) of every aggregatable field, in the order the model declares
+ * them.
+ */
+export declare function aggregateFields(model: ResourceModel): [field: string, type: AggregateFieldType][];

package/resource/utils/aggregate-util.js

@@ -0,0 +1,322 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAggregationPeriods = buildAggregationPeriods;
+exports.mapAggregationSelect = mapAggregationSelect;
+exports.mapAggregationResult = mapAggregationResult;
+exports.readAggregationBoundaries = readAggregationBoundaries;
+exports.aggregationRecordCount = aggregationRecordCount;
+exports.checkAggregationDateField = checkAggregationDateField;
+exports.aggregateFields = aggregateFields;
+const date_util_1 = require("./date-util");
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+/** The scalar types holding a numeric value, which every operator applies to. */
+const NUMERIC_TYPES = ['int', 'bigInt', 'float'];
+/** The scalar types holding a date value, which cannot be summed or averaged. */
+const DATE_TYPES = ['dateTime'];
+/** The operators resolved by reading a boundary record of the range instead of aggregating it. */
+const BOUNDARY_OPERATORS = ['first', 'last'];
+/** The Prisma selection counting every record of a range, regardless of the fields it holds. */
+const COUNT_ALL_FIELD = '_all';
+/** The aggregation operators applicable to a field, per kind of value. */
+const OPERATORS = {
+    numeric: ['count', 'sum', 'avg', 'min', 'max', ...BOUNDARY_OPERATORS],
+    date: ['count', 'min', 'max', ...BOUNDARY_OPERATORS]
+};
+/**
+ * Resolves an aggregation date range from its ISO string bounds and splits it into equally sized periods.
+ *
+ * @param {string} [from] - The ISO date string of the range start. Defaults to seven days before the range end.
+ * @param {string} [to] - The ISO date string of the range end. Defaults to the current date and time.
+ * @param {number} [step] - The size of a single period in units of the automatically selected time unit. If not
+ * provided, one unit is used and the unit is derived from the range length.
+ * @param {boolean} [safeIncrement=true] - Whether the period increments use the derived time unit and stay consistent
+ * across daylight saving time changes. When false, the step is interpreted in seconds.
+ * @return {AggregationPeriods} The resolved range bounds and one range per period, each labeled with its median date.
+ */
+function buildAggregationPeriods(from, to, step, safeIncrement = true) {
+    const toDate = (0, date_util_1.parseIsoDate)(to ?? new Date().toISOString());
+    const fromDate = from ? (0, date_util_1.parseIsoDate)(from) : (0, date_util_1.addDays)(toDate, -7);
+    const iterator = makeAggregationIterator(fromDate, toDate, step, safeIncrement);
+    const ranges = [];
+    let currentDate = new Date(fromDate.getTime());
+    while (currentDate < toDate) {
+        const date = currentDate;
+        const median = iterator.addPeriod(date, (iterator.step - 1) / 2);
+        currentDate = iterator.addPeriod(currentDate, iterator.step);
+        ranges.push({ from: date, to: currentDate, median });
+    }
+    return { fromDate, toDate, ranges };
+}
+/**
+ * Maps an aggregation selection to the operations that resolve it, splitting the operators the database aggregates in
+ * a single query from the `first` and `last` operators, which read the boundary records of the range instead. Every
+ * field is validated against the model it is aggregated on, and every operator against the kind of value its field
+ * holds, since only the numeric fields can be summed and averaged.
+ *
+ * @param {AggregateSelect<Object>} select - The operations to perform per field, with the operators of a field nested
+ * inside it. The operators set to false are left out.
+ * @param {string} resourceName - The name of the model the selection is aggregated on.
+ * @return {AggregationOperations} The Prisma aggregation arguments, keyed by the prefixed operator name with the
+ * selected fields nested inside, together with the fields read off the earliest and the latest record of the range.
+ * The arguments always count the records of the range when a boundary field was selected, so the boundary queries can
+ * be skipped for the empty ranges.
+ * @throws {ResourceError} `RESOURCE_INVALID_AGGREGATE` if the selection is not an object, selects no operation at all, names a field the model
+ * cannot aggregate, or applies an operator the kind of value of its field does not support.
+ */
+function mapAggregationSelect(select, resourceName) {
+    if (!(0, common_1.isPlainObject)(select)) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidAggregate, `${resourceName} aggregate select must be an object of fields to aggregate`, { model: resourceName });
+    }
+    const model = (0, core_1.injectModel)(resourceName);
+    const fieldTypes = new Map(aggregateFields(model));
+    const operations = {
+        aggregate: {},
+        first: [],
+        last: []
+    };
+    for (const [field, operators] of Object.entries(select)) {
+        const fieldType = fieldTypes.get(field);
+        if (!fieldType) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidAggregate, `Cannot aggregate the '${field}' field, it is not a numeric or date field of the ${model.name} model`, { model: model.name, field });
+        }
+        if (!(0, common_1.isPlainObject)(operators)) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidAggregate, `Cannot aggregate the '${field}' field, its value must be an object of aggregation operators`, { model: model.name, field });
+        }
+        for (const [operator, enabled] of Object.entries(operators)) {
+            if (!OPERATORS[fieldType].includes(operator)) {
+                throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidAggregate, `Cannot apply the '${operator}' operator to the ${fieldType} field '${field}', ` +
+                    `expected one of: ${OPERATORS[fieldType].join(', ')}`, { model: model.name, field, operator });
+            }
+            if (!enabled) {
+                continue;
+            }
+            if (isBoundaryOperator(operator)) {
+                operations[operator].push(field);
+            }
+            else {
+                (0, common_1.setValue)(operations.aggregate, `_${operator}.${field}`, true);
+            }
+        }
+    }
+    const hasBoundary = operations.first.length + operations.last.length > 0;
+    if (Object.keys(operations.aggregate).length === 0 && !hasBoundary) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidAggregate, `${resourceName} aggregate requires at least one field with a selected aggregation operator`, { model: resourceName });
+    }
+    // The record count of a range decides whether its boundary records have to be
+    // read at all, and it is also the only aggregation left to perform when the
+    // selection holds nothing but the boundary operators
+    if (hasBoundary) {
+        (0, common_1.setValue)(operations.aggregate, `_count.${COUNT_ALL_FIELD}`, true);
+    }
+    return operations;
+}
+/**
+ * Maps a Prisma aggregation result back to the response format by swapping the operator and field nesting, so a
+ * `{ _count: { views: 3 } }` result becomes the `{ views: { count: 3 } }` response value. The boundary record values
+ * are mapped the same way when they are merged into the result under their own `_first` and `_last` keys.
+ *
+ * @param {Object} result - The Prisma aggregation result, keyed by the prefixed operator name with the aggregated
+ * fields nested inside.
+ * @return {AggregateValue<Object>} The aggregated values keyed by field name, with the operator results nested inside.
+ * The record count of the range is left out, since it counts no field of its own.
+ */
+function mapAggregationResult(result) {
+    const aggregationMap = {};
+    for (const operator in result) {
+        const fields = result[operator];
+        for (const field in fields) {
+            if (field === COUNT_ALL_FIELD) {
+                continue;
+            }
+            (0, common_1.setValue)(aggregationMap, `${field}.${operator.substring(1)}`, fields[field]);
+        }
+    }
+    return aggregationMap;
+}
+/**
+ * Reads the `first` and `last` values of an aggregated range off its boundary records. The earliest and the latest
+ * record of the range are looked up by the same date field the range is sliced by, with the record id breaking the
+ * ties, and only the selected fields are read off them. The values of an empty range are resolved to null without
+ * querying for them, so a range the aggregation already counted as empty costs nothing.
+ *
+ * @param {ResourceClient} client - The model client the boundary records are read with, which is the transaction
+ * client of the aggregation.
+ * @param {Object} where - The database query of the aggregated range, applied unchanged to the boundary lookups.
+ * @param {string} dateField - The date field the range is sliced by, which the boundary records are ordered by.
+ * @param {AggregationOperations} operations - The operations holding the fields to read off each boundary record.
+ * @param {number} [recordCount] - The number of records in the range, used to skip the lookups of an empty range. When
+ * omitted, the lookups are always performed.
+ * @return {Promise<Object>} The boundary values keyed by the prefixed operator name (`_first` and `_last`) with the
+ * read fields nested inside, ready to be merged into the aggregation result of the range. Empty when no boundary field
+ * was selected.
+ */
+async function readAggregationBoundaries(client, where, dateField, operations, recordCount) {
+    const boundaries = {};
+    const readBoundary = async (operator, direction) => {
+        const fields = operations[operator];
+        if (fields.length === 0) {
+            return;
+        }
+        // An empty range holds no record to read the values off, and its fields are
+        // resolved to null the same way the database aggregations resolve theirs
+        const record = recordCount === 0
+            ? undefined
+            : await client.findFirst({
+                where,
+                // The id breaks the ties of the records sharing the same date, so
+                // the boundary of a range stays the same across identical requests
+                orderBy: [{ [dateField]: direction }, { id: direction }],
+                select: Object.fromEntries(fields.map((field) => [field, true]))
+            });
+        boundaries[`_${operator}`] = Object.fromEntries(fields.map((field) => [field, record?.[field] ?? null]));
+    };
+    await Promise.all([
+        readBoundary('first', 'asc'),
+        readBoundary('last', 'desc')
+    ]);
+    return boundaries;
+}
+/**
+ * Reads the record count a Prisma aggregation result holds for its range, as counted by the `_all` selection that
+ * {@link mapAggregationSelect} adds whenever a boundary field is selected.
+ *
+ * @param {Object} result - The Prisma aggregation result to read the count off.
+ * @return {number|undefined} The number of records in the range, or undefined when the result does not count them.
+ */
+function aggregationRecordCount(result) {
+    return (0, common_1.isPlainObject)(result?._count)
+        ? result._count[COUNT_ALL_FIELD]
+        : undefined;
+}
+/** Determines whether an operator reads a boundary record instead of aggregating the range. */
+function isBoundaryOperator(operator) {
+    return BOUNDARY_OPERATORS.includes(operator);
+}
+/**
+ * Validates the date field the aggregated range is applied on against the model it is aggregated on.
+ *
+ * @param {string} dateField - The name of the date field to validate.
+ * @param {string} resourceName - The name of the model the range is applied on.
+ * @return {string} The validated date field name.
+ * @throws {ResourceError} `RESOURCE_INVALID_AGGREGATE` if the model has no date field under that name.
+ */
+function checkAggregationDateField(dateField, resourceName) {
+    const model = (0, core_1.injectModel)(resourceName);
+    const dateFields = aggregateFields(model)
+        .filter(([, type]) => type === 'date')
+        .map(([field]) => field);
+    if (!dateFields.includes(dateField)) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidAggregate, `Cannot aggregate over the '${dateField}' field, it is not a date field of the ${model.name} model` +
+            (dateFields.length > 0
+                ? `, expected one of: ${dateFields.join(', ')}`
+                : ''), { model: model.name, field: dateField });
+    }
+    return dateField;
+}
+/**
+ * Lists the aggregatable fields of a resource model together with the kind of value they hold. The id is aggregatable
+ * when it is numeric, the audit fields follow the audit configuration of the model, and the scalars are aggregatable
+ * when they hold a single numeric or date value and are not hidden. The virtual fields are never aggregatable, since
+ * they have no column of their own.
+ *
+ * @param {ResourceModel} model - The resource model whose fields are listed.
+ * @return {Array} The name and kind (`numeric` or `date`) of every aggregatable field, in the order the model declares
+ * them.
+ */
+function aggregateFields(model) {
+    const fields = [];
+    if ((model.config.id?.type ?? 'int') !== 'string') {
+        fields.push(['id', 'numeric']);
+    }
+    const auditFields = {
+        updatedAt: true,
+        createdAt: true,
+        createdById: true,
+        ...(model.config.audit ?? {})
+    };
+    for (const [fieldName, included] of Object.entries(auditFields)) {
+        if (included) {
+            fields.push([
+                fieldName,
+                fieldName === 'createdById' ? 'numeric' : 'date'
+            ]);
+        }
+    }
+    for (const [fieldName, scalar] of Object.entries(model.config.scalars ?? {})) {
+        if (scalar.hidden || scalar.array) {
+            continue;
+        }
+        if (NUMERIC_TYPES.includes(scalar.type)) {
+            fields.push([fieldName, 'numeric']);
+        }
+        else if (DATE_TYPES.includes(scalar.type)) {
+            fields.push([fieldName, 'date']);
+        }
+    }
+    return fields;
+}
+/**
+ * Builds the period iterator used to split an aggregation date range into equally sized periods. When no step is
+ * provided, a step of one is used with the time unit derived from the range length, and the returned increment
+ * function compensates for daylight saving time offset changes so every period keeps the time zone offset of its
+ * start date.
+ *
+ * @param {Date} fromDate - The start of the aggregated date range.
+ * @param {Date} toDate - The end of the aggregated date range.
+ * @param {number} [step] - The size of a single period in units of the selected time unit. If not provided, a step of
+ * one is used with the time unit derived from the range length (seconds up to a minute, minutes up to an hour, hours
+ * up to a day, days up to a month, months up to a year, and years beyond that).
+ * @param {boolean} [safeIncrement=true] - Whether the increments use the derived time unit. When false, the step is
+ * interpreted in seconds.
+ * @return {{addPeriod: PeriodIncrementFn, step: number}} The iterator holding the resolved step amount and the
+ * `addPeriod` function that adds a number of periods to a date while preserving the time zone offset of that date.
+ */
+function makeAggregationIterator(fromDate, toDate, step, safeIncrement = true) {
+    let stepAmount = step;
+    let incrementFn = date_util_1.addSeconds;
+    if (!stepAmount) {
+        const diffInSeconds = (0, date_util_1.differenceInSeconds)(toDate, fromDate);
+        const diffInMonths = (0, date_util_1.differenceInMonths)(toDate, fromDate);
+        const diffInYears = (0, date_util_1.differenceInYears)(toDate, fromDate);
+        stepAmount = 1;
+        // 1-second step if the difference is less than or equal to 1 minute
+        if (diffInSeconds <= 60) {
+            incrementFn = date_util_1.addSeconds;
+        }
+        // 1-minute step if the difference is less than or equal to 1 hour
+        else if (diffInSeconds <= 3600) {
+            incrementFn = date_util_1.addMinutes;
+        }
+        // 1-hour step if the difference is less than or equal to 1 day
+        else if (diffInSeconds <= 86400) {
+            incrementFn = date_util_1.addHours;
+        }
+        // 1-day step if the difference is less than or equal to 1 month
+        else if (diffInMonths <= 1) {
+            incrementFn = date_util_1.addDays;
+        }
+        // 1-month step if the difference is less than or equal to 1 year
+        else if (diffInYears <= 1) {
+            incrementFn = date_util_1.addMonths;
+        }
+        // 1-year step if the difference is equal to 1 year or more
+        else {
+            incrementFn = date_util_1.addYears;
+        }
+    }
+    // A higher-order function that adjusts date increments to account for
+    // changes in daylight saving time (DST). When incrementing dates in time
+    // zones that observe DST, this function ensures that the resulting date
+    // remains consistent with the original date's time zone offset.
+    const dstAgnosticFn = (fn) => {
+        return (date, amount) => {
+            const endDate = fn(date, amount);
+            return (0, date_util_1.addMinutes)(endDate, date.getTimezoneOffset() - endDate.getTimezoneOffset());
+        };
+    };
+    return {
+        addPeriod: dstAgnosticFn(safeIncrement ? incrementFn : date_util_1.addSeconds),
+        step: stepAmount
+    };
+}

package/resource/utils/cursor-util.d.ts

@@ -0,0 +1,60 @@
+import { QueryResponse, ResourceId } from '@appweaver/common';
+/** The cursors a query response carries, kept in step with the response contract. */
+export type PageCursors = Pick<QueryResponse<unknown>, 'nextCursor' | 'prevCursor'>;
+/** A decoded cursor, holding the record it points at and the direction to page in. */
+export type DecodedCursor = {
+    id: ResourceId;
+    /** True when the cursor pages towards the preceding records */
+    backward: boolean;
+};
+/**
+ * Builds the fingerprint identifying the query a cursor belongs to. A cursor
+ * only yields the intended records while the resource, the query, and the order
+ * stay the same, so it carries the fingerprint and is rejected on mismatch.
+ *
+ * @param {string} resourceName - The name of the queried model.
+ * @param {Object} query - The mapped database query the cursor was issued for.
+ * @param {Object[]} orderBy - The mapped order entries the cursor was issued for.
+ * @return {string} The fingerprint of the query.
+ */
+export declare function queryFingerprint(resourceName: string, query: any, orderBy: any[]): string;
+/**
+ * Encodes the cursor of a page adjacent to a query result. The direction belongs
+ * to the cursor rather than to the request, so a caller cannot pair one with a
+ * direction it was not issued for.
+ *
+ * @param {ResourceId} id - The primary key of the record the page continues from.
+ * @param {string} fingerprint - The fingerprint of the query, as built by
+ * {@link queryFingerprint}.
+ * @param {boolean} [backward] - Whether the cursor pages towards the preceding
+ * records.
+ * @return {string} The encoded cursor.
+ */
+export declare function encodeCursor(id: ResourceId, fingerprint: string, backward?: boolean): string;
+/**
+ * Builds the cursors of the pages adjacent to a returned page, each addressing
+ * the record of this page it continues from. A page that has no neighbour in a
+ * direction, and an empty page, yield null rather than an absent cursor.
+ *
+ * @param {Object[]} resources - The records of the returned page, in the order
+ * they were queried in.
+ * @param {string} fingerprint - The fingerprint of the query the page belongs to.
+ * @param {boolean} hasNext - Whether a page follows the returned one.
+ * @param {boolean} hasPrev - Whether a page precedes the returned one.
+ * @return {PageCursors} The cursors of the existing adjacent pages.
+ */
+export declare function pageCursors<T>(resources: T[], fingerprint: string, hasNext: boolean, hasPrev: boolean): PageCursors;
+/**
+ * Decodes the cursor a query request carries, resolving the record the page
+ * continues from and the direction it runs in.
+ *
+ * @param {string} [cursor] - The cursor of the request, which may be the null
+ * one of a page that does not exist.
+ * @param {string} fingerprint - The fingerprint of the query the cursor is used
+ * on, as built by {@link queryFingerprint}.
+ * @return {DecodedCursor | undefined} The decoded cursor, or `undefined` when the
+ * request carries none.
+ * @throws {ResourceError} `RESOURCE_INVALID_CURSOR` if the cursor is malformed, or was issued for another
+ * resource, filter, or sort order.
+ */
+export declare function decodeCursor(cursor: string | null | undefined, fingerprint: string): DecodedCursor | undefined;

package/resource/utils/cursor-util.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryFingerprint = queryFingerprint;
+exports.encodeCursor = encodeCursor;
+exports.pageCursors = pageCursors;
+exports.decodeCursor = decodeCursor;
+const common_1 = require("@appweaver/common");
+/**
+ * Builds the fingerprint identifying the query a cursor belongs to. A cursor
+ * only yields the intended records while the resource, the query, and the order
+ * stay the same, so it carries the fingerprint and is rejected on mismatch.
+ *
+ * @param {string} resourceName - The name of the queried model.
+ * @param {Object} query - The mapped database query the cursor was issued for.
+ * @param {Object[]} orderBy - The mapped order entries the cursor was issued for.
+ * @return {string} The fingerprint of the query.
+ */
+function queryFingerprint(resourceName, query, orderBy) {
+    const serialized = stableStringify([resourceName, query ?? {}, orderBy]);
+    return (0, common_1.makeHash)(serialized, 'sha256', 'base64url').slice(0, 16);
+}
+/**
+ * Encodes the cursor of a page adjacent to a query result. The direction belongs
+ * to the cursor rather than to the request, so a caller cannot pair one with a
+ * direction it was not issued for.
+ *
+ * @param {ResourceId} id - The primary key of the record the page continues from.
+ * @param {string} fingerprint - The fingerprint of the query, as built by
+ * {@link queryFingerprint}.
+ * @param {boolean} [backward] - Whether the cursor pages towards the preceding
+ * records.
+ * @return {string} The encoded cursor.
+ */
+function encodeCursor(id, fingerprint, backward = false) {
+    const payload = { i: id, f: fingerprint };
+    if (backward) {
+        payload.b = true;
+    }
+    return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+}
+/**
+ * Builds the cursors of the pages adjacent to a returned page, each addressing
+ * the record of this page it continues from. A page that has no neighbour in a
+ * direction, and an empty page, yield null rather than an absent cursor.
+ *
+ * @param {Object[]} resources - The records of the returned page, in the order
+ * they were queried in.
+ * @param {string} fingerprint - The fingerprint of the query the page belongs to.
+ * @param {boolean} hasNext - Whether a page follows the returned one.
+ * @param {boolean} hasPrev - Whether a page precedes the returned one.
+ * @return {PageCursors} The cursors of the existing adjacent pages.
+ */
+function pageCursors(resources, fingerprint, hasNext, hasPrev) {
+    // A queried record always carries its primary key, which a model type need
+    // not declare
+    const first = resources[0];
+    const last = resources[resources.length - 1];
+    if (!first || !last) {
+        return { nextCursor: null, prevCursor: null };
+    }
+    return {
+        nextCursor: hasNext ? encodeCursor(last.id, fingerprint) : null,
+        prevCursor: hasPrev ? encodeCursor(first.id, fingerprint, true) : null
+    };
+}
+/**
+ * Decodes the cursor a query request carries, resolving the record the page
+ * continues from and the direction it runs in.
+ *
+ * @param {string} [cursor] - The cursor of the request, which may be the null
+ * one of a page that does not exist.
+ * @param {string} fingerprint - The fingerprint of the query the cursor is used
+ * on, as built by {@link queryFingerprint}.
+ * @return {DecodedCursor | undefined} The decoded cursor, or `undefined` when the
+ * request carries none.
+ * @throws {ResourceError} `RESOURCE_INVALID_CURSOR` if the cursor is malformed, or was issued for another
+ * resource, filter, or sort order.
+ */
+function decodeCursor(cursor, fingerprint) {
+    if (!cursor) {
+        return undefined;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch (e) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidCursor, 'Invalid pagination cursor', {}, { cause: e });
+    }
+    if (!(0, common_1.isPlainObject)(payload) || payload.i === undefined) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidCursor, 'Invalid pagination cursor');
+    }
+    if (payload.f !== fingerprint) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidCursor, 'Pagination cursor does not match the filter and sort of this query');
+    }
+    return { id: payload.i, backward: payload.b === true };
+}
+/**
+ * Serializes a value with its object keys in a stable order, so two equal
+ * queries fingerprint identically whatever order their properties arrived in.
+ *
+ * @param {any} value - The value to serialize.
+ * @return {string} The serialized value.
+ */
+function stableStringify(value) {
+    if ((0, common_1.isArray)(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if ((0, common_1.isPlainObject)(value)) {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}

package/resource/utils/date-util.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Parses an ISO 8601 date string. A date without a time is the local midnight of that day, a date and time without an
+ * offset is local, and one with an offset is that exact instant.
+ *
+ * @param {string} value - The ISO date string.
+ * @return {Date} The parsed date, invalid when the string is not a date.
+ */
+export declare function parseIsoDate(value: string): Date;
+export declare function addSeconds(date: Date, amount: number): Date;
+export declare function addMinutes(date: Date, amount: number): Date;
+export declare function addHours(date: Date, amount: number): Date;
+/** Adds whole local days, keeping the time of day across daylight saving time changes. */
+export declare function addDays(date: Date, amount: number): Date;
+/** Adds whole local months, clamping the day to the last day of a shorter month (January 31 plus one is February 28). */
+export declare function addMonths(date: Date, amount: number): Date;
+export declare function addYears(date: Date, amount: number): Date;
+/** Returns the whole seconds between two dates, truncated toward zero. */
+export declare function differenceInSeconds(laterDate: Date, earlierDate: Date): number;
+/** Returns the full local months between two dates, negative when the first date is the earlier one. */
+export declare function differenceInMonths(laterDate: Date, earlierDate: Date): number;
+/** Returns the full local years between two dates, negative when the first date is the earlier one. */
+export declare function differenceInYears(laterDate: Date, earlierDate: Date): number;