@mintlify/common 1.0.1310 → 1.0.1312

package/dist/databases/query/types.d.ts

@@ -0,0 +1,69 @@
+export type QueryValue = string | number | boolean | null;
+export declare const COMPARE_OPS: readonly ['eq', 'ne', 'lt', 'lte', 'gt', 'gte'];
+export type CompareOp = (typeof COMPARE_OPS)[number];
+export declare const TEXT_OPS: readonly ['contains', 'startsWith', 'endsWith'];
+export type TextOp = (typeof TEXT_OPS)[number];
+export type QueryExpr = {
+    kind: 'column';
+    id: string;
+} | {
+    kind: 'literal';
+    value: QueryValue;
+} | {
+    kind: 'and' | 'or';
+    args: QueryExpr[];
+} | {
+    kind: 'not';
+    arg: QueryExpr;
+} | {
+    kind: 'compare';
+    op: CompareOp;
+    left: QueryExpr;
+    right: QueryExpr;
+} | {
+    kind: 'text';
+    op: TextOp;
+    left: QueryExpr;
+    right: QueryExpr;
+} | {
+    kind: 'isEmpty';
+    arg: QueryExpr;
+} | {
+    kind: 'in';
+    arg: QueryExpr;
+    values: QueryValue[];
+};
+export type SortDirection = 'asc' | 'desc';
+export type QuerySort = {
+    columnId: string;
+    direction: SortDirection;
+}[];
+export declare const AGGREGATE_FNS: readonly ['count', 'count_empty', 'count_filled', 'sum', 'avg', 'min', 'max'];
+export type AggregateFn = (typeof AGGREGATE_FNS)[number];
+export type QueryAggregate = {
+    columnId: string;
+    fn: AggregateFn;
+};
+export type QueryRequest = {
+    filter?: QueryExpr;
+    sort?: QuerySort;
+    aggregates?: QueryAggregate[];
+};
+export type QueryColumn = {
+    id: string;
+    type: string;
+};
+export type QueryRow = {
+    id: string;
+    createdAt: string;
+    columns: Readonly<Record<string, unknown>>;
+};
+export declare const QUERY_LIMITS: {
+    readonly depth: 16;
+    readonly nodes: 256;
+    readonly inValues: 200;
+    readonly sortKeys: 3;
+    readonly aggregates: 64;
+    readonly literalLength: 10000;
+};
+export declare const CLIENT_ONLY = "formula columns are client-only";

package/dist/databases/query/types.js

@@ -0,0 +1,20 @@
+export const COMPARE_OPS = ['eq', 'ne', 'lt', 'lte', 'gt', 'gte'];
+export const TEXT_OPS = ['contains', 'startsWith', 'endsWith'];
+export const AGGREGATE_FNS = [
+    'count',
+    'count_empty',
+    'count_filled',
+    'sum',
+    'avg',
+    'min',
+    'max',
+];
+export const QUERY_LIMITS = {
+    depth: 16,
+    nodes: 256,
+    inValues: 200,
+    sortKeys: 3,
+    aggregates: 64,
+    literalLength: 10000,
+};
+export const CLIENT_ONLY = 'formula columns are client-only';

package/dist/databases/query/validate.d.ts

@@ -0,0 +1,8 @@
+import { type QueryRequest } from './types.js';
+export type QueryError = {
+    message: string;
+    fields: Record<string, string>;
+};
+export declare const validateQueryExpr: (expr: unknown, path?: string) => QueryError | null;
+export declare const validateQueryRequest: (request: unknown) => QueryError | null;
+export declare const isValidQueryRequest: (request: unknown) => request is QueryRequest;

package/dist/databases/query/validate.js

@@ -0,0 +1,138 @@
+import { AGGREGATE_FNS, COMPARE_OPS, QUERY_LIMITS, TEXT_OPS, } from './types.js';
+const COMPARE = new Set(COMPARE_OPS);
+const TEXT = new Set(TEXT_OPS);
+const FNS = new Set(AGGREGATE_FNS);
+const DIRECTIONS = new Set(['asc', 'desc']);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const own = (record, key) => Object.hasOwn(record, key) ? record[key] : undefined;
+const isValue = (value) => value === null ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value)) ||
+    (typeof value === 'string' && value.length <= QUERY_LIMITS.literalLength);
+class Fields {
+    constructor() {
+        this.fields = {};
+    }
+    fail(path, message) {
+        if (!Object.hasOwn(this.fields, path))
+            this.fields[path] = message;
+    }
+    error() {
+        return Object.keys(this.fields).length
+            ? { message: 'query is invalid', fields: this.fields }
+            : null;
+    }
+}
+const checkExpr = (root, at, out) => {
+    const pending = [
+        { node: root, path: at, depth: 1 },
+    ];
+    let nodes = 0;
+    for (let next = pending.pop(); next; next = pending.pop()) {
+        const { node, path, depth } = next;
+        if (++nodes > QUERY_LIMITS.nodes)
+            return out.fail(at, `has more than ${QUERY_LIMITS.nodes} nodes`);
+        if (depth > QUERY_LIMITS.depth)
+            return out.fail(at, `nests deeper than ${QUERY_LIMITS.depth}`);
+        if (!isRecord(node)) {
+            out.fail(path, 'expected an expression');
+            continue;
+        }
+        const child = (key) => pending.push({ node: own(node, key), path: `${path}.${key}`, depth: depth + 1 });
+        const kind = own(node, 'kind');
+        switch (kind) {
+            case 'column':
+                if (typeof own(node, 'id') !== 'string')
+                    out.fail(`${path}.id`, 'expected a column id');
+                break;
+            case 'literal':
+                if (!isValue(own(node, 'value'))) {
+                    out.fail(`${path}.value`, 'expected a string, number, boolean or null');
+                }
+                break;
+            case 'and':
+            case 'or': {
+                const args = own(node, 'args');
+                if (!Array.isArray(args)) {
+                    out.fail(`${path}.args`, 'expected a list of expressions');
+                    break;
+                }
+                if (nodes + pending.length + args.length > QUERY_LIMITS.nodes) {
+                    return out.fail(at, `has more than ${QUERY_LIMITS.nodes} nodes`);
+                }
+                args.forEach((arg, index) => pending.push({ node: arg, path: `${path}.args.${index}`, depth: depth + 1 }));
+                break;
+            }
+            case 'not':
+            case 'isEmpty':
+                child('arg');
+                break;
+            case 'compare':
+            case 'text':
+                if (!(kind === 'compare' ? COMPARE : TEXT).has(own(node, 'op'))) {
+                    out.fail(`${path}.op`, `unknown ${kind} operator`);
+                }
+                child('left');
+                child('right');
+                break;
+            case 'in': {
+                child('arg');
+                const values = own(node, 'values');
+                if (!Array.isArray(values) || !values.every(isValue)) {
+                    out.fail(`${path}.values`, 'expected a list of values');
+                }
+                else if (values.length > QUERY_LIMITS.inValues) {
+                    out.fail(`${path}.values`, `at most ${QUERY_LIMITS.inValues} values`);
+                }
+                break;
+            }
+            default:
+                out.fail(`${path}.kind`, 'unknown expression kind');
+        }
+    }
+};
+const checkList = (value, path, limit, noun, out, item) => {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        return out.fail(path, `expected a list of ${noun}`);
+    if (value.length > limit)
+        return out.fail(path, `at most ${limit} ${noun}`);
+    value.forEach((entry, index) => {
+        const at = `${path}.${index}`;
+        if (!isRecord(entry))
+            out.fail(at, 'expected an object');
+        else
+            item(entry, at);
+    });
+};
+export const validateQueryExpr = (expr, path = 'filter') => {
+    const out = new Fields();
+    checkExpr(expr, path, out);
+    return out.error();
+};
+export const validateQueryRequest = (request) => {
+    const out = new Fields();
+    if (!isRecord(request)) {
+        out.fail('request', 'expected an object');
+        return out.error();
+    }
+    const filter = own(request, 'filter');
+    if (filter !== undefined)
+        checkExpr(filter, 'filter', out);
+    checkList(own(request, 'sort'), 'sort', QUERY_LIMITS.sortKeys, 'sort keys', out, (key, at) => {
+        if (typeof own(key, 'columnId') !== 'string')
+            out.fail(`${at}.columnId`, 'expected a column id');
+        if (!DIRECTIONS.has(own(key, 'direction')))
+            out.fail(`${at}.direction`, 'expected asc or desc');
+    });
+    checkList(own(request, 'aggregates'), 'aggregates', QUERY_LIMITS.aggregates, 'aggregates', out, (aggregate, at) => {
+        if (typeof own(aggregate, 'columnId') !== 'string') {
+            out.fail(`${at}.columnId`, 'expected a column id');
+        }
+        if (!FNS.has(own(aggregate, 'fn')))
+            out.fail(`${at}.fn`, 'unknown aggregate');
+    });
+    return out.error();
+};
+export const isValidQueryRequest = (request) => validateQueryRequest(request) === null;

package/dist/databases/query/values.d.ts

@@ -0,0 +1,4 @@
+export declare const normalizeDate: (value: unknown) => string | null;
+export declare const isEmptyValue: (value: unknown) => boolean;
+export declare const asciiLower: (value: string) => string;
+export declare const compareCodePoints: (a: string, b: string) => -1 | 0 | 1;

package/dist/databases/query/values.js

@@ -0,0 +1,36 @@
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2}))?$/;
+export const normalizeDate = (value) => {
+    if (typeof value !== 'string')
+        return null;
+    const match = ISO_DATE.exec(value);
+    if (!match)
+        return null;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const calendar = new Date(Date.UTC(year, month - 1, day));
+    const valid = calendar.getUTCFullYear() === year &&
+        calendar.getUTCMonth() === month - 1 &&
+        calendar.getUTCDate() === day;
+    const time = Date.parse(value);
+    return valid && !Number.isNaN(time) ? new Date(time).toISOString() : null;
+};
+export const isEmptyValue = (value) => value === null ||
+    value === undefined ||
+    value === '' ||
+    (Array.isArray(value) && value.length === 0);
+const UPPER = /[A-Z]/;
+export const asciiLower = (value) => UPPER.test(value)
+    ? value.replace(/[A-Z]/g, (char) => String.fromCharCode(char.charCodeAt(0) + 32))
+    : value;
+export const compareCodePoints = (a, b) => {
+    var _a, _b;
+    const length = Math.min(a.length, b.length);
+    for (let index = 0; index < length; index++) {
+        const left = (_a = a.codePointAt(index)) !== null && _a !== void 0 ? _a : 0;
+        const right = (_b = b.codePointAt(index)) !== null && _b !== void 0 ? _b : 0;
+        if (left !== right)
+            return left < right ? -1 : 1;
+        if (left > 0xffff)
+            index++;
+    }
+    return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;
+};