@mintlify/common 1.0.1309 → 1.0.1311

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;
+};

package/dist/mdx/snippets/resolveAllImports.d.ts

@@ -5,6 +5,7 @@ import { type PackageImportOptions } from '../islands/packageImports.js';
 export type ResolveImportsWarning = {
     type: 'invalid-import-path' | 'missing-file' | 'import-resolution-error' | 'default-import-no-default-export' | 'export-collision' | 'undeclared-package' | 'package-import-conflict';
     message: string;
+    file?: string;
 };
 export declare const resolveAllImports: (params: {
     snippets: (FileType & {

package/dist/mdx/snippets/resolveAllImports.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { jsx, toJs } from 'estree-util-to-js';
 import { remove } from 'unist-util-remove';
 import { visit } from 'unist-util-visit';
+import { normalizeRelativePath } from '../../fs/normalizeRelativePath.js';
 import { MdxImportSpecifier } from '../../types/mdx/snippets/import.js';
 import { createImportNode, isDeclaredPackageImport, isNonHostBareImport, mergeImports, } from '../islands/packageImports.js';
 import { estreeIsProgram, isImportDeclaration, isMdxJsEsm } from '../utils.js';
@@ -109,6 +110,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
     var _a;
     var _b, _c, _d, _e;
     const { snippets, fileWithImports, onWarning, packages } = params;
+    const file = normalizeRelativePath(fileWithImports.filename);
     let ast = fileWithImports.tree;
     const kept = packages && /\.mdx?$/.test(fileWithImports.filename)
         ? takePackageReExports(ast, packages.packageNames)
@@ -125,7 +127,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
             }
             const message = `Package ${(_c = getSpecifierPackageName(source)) !== null && _c !== void 0 ? _c : source} imported in ${fileWithImports.filename} is not declared in package.json dependencies.`;
             if (onWarning) {
-                onWarning({ type: 'undeclared-package', message });
+                onWarning({ type: 'undeclared-package', message, file });
             }
             else {
                 console.log(message);
@@ -139,7 +141,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
         if (resolvedPath == null) {
             const message = `Invalid import path ${source} in ${fileWithImports.filename}. Only local imports are supported.`;
             if (onWarning) {
-                onWarning({ type: 'invalid-import-path', message });
+                onWarning({ type: 'invalid-import-path', message, file });
             }
             else {
                 console.log(message);
@@ -150,7 +152,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
         if (foundSnippet == undefined) {
             const message = `Could not find file ${resolvedPath} - imported from ${fileWithImports.filename}`;
             if (onWarning) {
-                onWarning({ type: 'missing-file', message });
+                onWarning({ type: 'missing-file', message, file });
             }
             else {
                 console.log(message);
@@ -178,7 +180,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
                 importedSnippet.tree.children.every((node) => node.type === 'yaml' || node.type === 'mdxjsEsm')) {
                 const message = `Default import "${specifier.name}" in ${fileWithImports.filename} will not render — ${resolvedPath} has no default export. Use a named import instead: import { ExportName } from '${source}'`;
                 if (onWarning) {
-                    onWarning({ type: 'default-import-no-default-export', message });
+                    onWarning({ type: 'default-import-no-default-export', message, file });
                 }
                 else {
                     console.log(message);
@@ -187,7 +189,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
             try {
                 const contentWithResolvedImport = yield resolveImport(specifier, ast, importedSnippet.tree, exportMap, (warning) => {
                     // the collision itself doesn't know which page it happened in, so add it here
-                    const located = Object.assign(Object.assign({}, warning), { message: `${warning.message} (in ${fileWithImports.filename}, importing ${resolvedPath})` });
+                    const located = Object.assign(Object.assign({}, warning), { message: `${warning.message} (in ${fileWithImports.filename}, importing ${resolvedPath})`, file });
                     if (onWarning) {
                         onWarning(located);
                     }
@@ -203,7 +205,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
             catch (err) {
                 const message = `Error resolving import "${specifier.name}" in ${fileWithImports.filename}: ${err instanceof Error ? err.message : String(err)}`;
                 if (onWarning) {
-                    onWarning({ type: 'import-resolution-error', message });
+                    onWarning({ type: 'import-resolution-error', message, file });
                 }
                 else {
                     console.log(message);
@@ -221,7 +223,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
     for (const { local, first, second } of conflicts) {
         const message = `${local} is imported twice in ${fileWithImports.filename}, as ${first} and as ${second}. Snippets inlined into a page share its imports, so import one of them under another name.`;
         if (onWarning) {
-            onWarning({ type: 'package-import-conflict', message });
+            onWarning({ type: 'package-import-conflict', message, file });
         }
         else {
             console.log(message);