@mintlify/common 1.0.1310 → 1.0.1311

package/dist/databases/formula/analyze.d.ts

@@ -0,0 +1,31 @@
+import { type FormulaNode, type FormulaRefNode } from './ast.js';
+import { FormulaError } from './errors.js';
+import { Schema } from './schema.js';
+import { type FormulaColumn, type TypeSet } from './types.js';
+export type Analysis = {
+    type: TypeSet;
+    diagnostics: FormulaError[];
+    failed: boolean;
+    cyclic: boolean;
+    height: number;
+    volatile: boolean;
+    truncated: boolean;
+    columns: Map<FormulaRefNode, FormulaColumn>;
+    types: Map<FormulaNode, TypeSet>;
+    options: Map<FormulaNode, string[] | null>;
+    dates: Map<FormulaNode, Date>;
+    days: Map<FormulaNode, DayRange>;
+    memberships: Map<FormulaNode, FormulaColumn>;
+};
+export type DayRange = {
+    start: Date;
+    end: Date;
+};
+export declare const analyze: (ast: FormulaNode, schema: Schema) => Analysis;
+export declare const schemaFor: (columns: readonly FormulaColumn[]) => Schema;
+export declare const analyzeFor: (ast: FormulaNode, columns: readonly FormulaColumn[], columnId?: string) => {
+    analysis: Analysis;
+    schema: Schema;
+    ast: FormulaNode;
+    stored?: FormulaColumn;
+};

package/dist/databases/formula/analyze.js

@@ -0,0 +1,296 @@
+import { normalizeDate } from '../query/values.js';
+import { COMPARISONS, } from './ast.js';
+import { parseDateUnit } from './dates.js';
+import { FormulaError } from './errors.js';
+import { arityMessage, DATE_FUNCTIONS, getFunction } from './functions.js';
+import { FORMULA_LIMITS } from './limits.js';
+import { Schema } from './schema.js';
+import { ANY, BOOLEAN, DATE, describeTypes, NUMBER, STRING, } from './types.js';
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86400000;
+const ORDERED = NUMBER | STRING | DATE;
+const isSelect = (column) => (column === null || column === void 0 ? void 0 : column.type) === 'select' || (column === null || column === void 0 ? void 0 : column.type) === 'multi_select';
+export const analyze = (ast, schema) => {
+    const analysis = {
+        type: ANY,
+        diagnostics: [],
+        failed: false,
+        cyclic: false,
+        height: 0,
+        volatile: false,
+        truncated: false,
+        columns: new Map(),
+        types: new Map(),
+        options: new Map(),
+        dates: new Map(),
+        days: new Map(),
+        memberships: new Map(),
+    };
+    const report = (code, message, span, severity = 'error') => {
+        analysis.diagnostics.push(new FormulaError(code, message, span.start, span.end, severity));
+    };
+    const refColumn = (node) => node.kind === 'ref' ? analysis.columns.get(node) : undefined;
+    const visitRef = (node) => {
+        const nameSpan = node.form === 'bare' ? node : { start: node.nameStart, end: node.nameEnd };
+        const column = node.id === undefined ? schema.byName.get(node.name) : schema.byId.get(node.id);
+        if (!column) {
+            const label = node.id === undefined ? node.name : `#${node.id}`;
+            report('unknown_property', `Unknown property '${label}'`, nameSpan);
+            return ANY;
+        }
+        analysis.columns.set(node, column);
+        if (column.type !== 'formula')
+            return schema.storedType(column);
+        const info = schema.formula(column);
+        analysis.height = Math.max(analysis.height, info.height + 1);
+        analysis.volatile || (analysis.volatile = info.volatile);
+        analysis.truncated || (analysis.truncated = info.truncated);
+        if (!info.cyclic && info.height + 1 > FORMULA_LIMITS.depth) {
+            report('depth', 'Formula properties are nested too deeply', node);
+        }
+        else if (info.cyclic) {
+            report('cycle', `Circular reference to '${column.name}'`, node);
+            analysis.cyclic = true;
+        }
+        else if (info.failed) {
+            report('dependency', `Property '${column.name}' has an error`, node);
+        }
+        return info.type;
+    };
+    const resolveOption = (literal, column) => {
+        if (literal.kind !== 'string')
+            return;
+        if (literal.value === '')
+            return;
+        const { idsByLabel, labelById } = schema.optionsOf(column);
+        const ids = idsByLabel.get(literal.value);
+        if (ids === undefined) {
+            report('unknown_option', `'${literal.value}' is not an option of '${column.name}'`, literal, 'warning');
+        }
+        analysis.options.set(literal, ids !== null && ids !== void 0 ? ids : (labelById.has(literal.value) ? null : [literal.value]));
+    };
+    const coerceDate = (literal) => {
+        if (literal.kind !== 'string')
+            return false;
+        const normalized = normalizeDate(literal.value);
+        if (normalized === null) {
+            report('type', `'${literal.value}' is not an ISO 8601 date`, literal);
+        }
+        else {
+            analysis.dates.set(literal, new Date(normalized));
+        }
+        return true;
+    };
+    const visitCompare = (node, left, right) => {
+        const operator = { start: node.operatorStart, end: node.operatorEnd };
+        const sides = [
+            [node.left, node.right],
+            [node.right, node.left],
+        ];
+        for (const [side, other] of sides) {
+            const column = refColumn(side);
+            if (!isSelect(column) || !column)
+                continue;
+            if (column.type === 'multi_select') {
+                if (node.operator !== '==' && node.operator !== '!=') {
+                    report('type', `'${column.name}' is a multi-select and only supports == and !=`, operator);
+                    return BOOLEAN;
+                }
+                if (other.kind !== 'string') {
+                    report('type', `Compare '${column.name}' with an option name`, other);
+                    return BOOLEAN;
+                }
+            }
+            resolveOption(other, column);
+        }
+        for (const [side, other] of sides) {
+            if (side.kind === 'string' && side.value === '') {
+                report('empty_comparison', 'Comparisons with "" are always false; use empty()', side, 'warning');
+            }
+            const sideType = side === node.left ? left : right;
+            if (side.kind === 'string' && side.value === '') {
+                if (side === node.left)
+                    left = right;
+                else
+                    right = left;
+                continue;
+            }
+            if (sideType === DATE && other.kind === 'string' && other.value !== '') {
+                if (coerceDate(other)) {
+                    if (other === node.left)
+                        left = DATE;
+                    else
+                        right = DATE;
+                }
+            }
+        }
+        const shared = left & right;
+        if (!shared) {
+            report('type', `Cannot compare ${describeTypes(left)} and ${describeTypes(right)}`, operator);
+        }
+        else if (node.operator !== '==' && node.operator !== '!=' && !(shared & ORDERED)) {
+            report('type', `Cannot order ${describeTypes(shared)} values`, operator);
+        }
+        return BOOLEAN;
+    };
+    const visitBinary = (node) => {
+        const left = visit(node.left);
+        const right = visit(node.right);
+        const operator = { start: node.operatorStart, end: node.operatorEnd };
+        if (COMPARISONS.has(node.operator))
+            return visitCompare(node, left, right);
+        if (node.operator === 'and' || node.operator === 'or') {
+            for (const [side, types] of [
+                [node.left, left],
+                [node.right, right],
+            ]) {
+                if (!(types & BOOLEAN)) {
+                    report('type', `Expected a boolean for '${node.operator}'`, side);
+                }
+            }
+            return BOOLEAN;
+        }
+        if (node.operator === '+') {
+            const sum = (left & right & (NUMBER | STRING));
+            if (!sum) {
+                report('type', `Cannot add ${describeTypes(left)} and ${describeTypes(right)}`, operator);
+                return NUMBER | STRING;
+            }
+            return sum;
+        }
+        for (const [side, types] of [
+            [node.left, left],
+            [node.right, right],
+        ]) {
+            if (!(types & NUMBER))
+                report('type', `Expected a number for '${node.operator}'`, side);
+        }
+        return NUMBER;
+    };
+    const visitCall = (node) => {
+        if (node.name === 'now')
+            analysis.volatile = true;
+        const types = node.args.map(visit);
+        const fn = getFunction(node.name);
+        const nameSpan = { start: node.start, end: node.start + node.name.length };
+        if (!fn) {
+            report('unknown_function', `Unknown function '${node.name}'`, nameSpan);
+            return ANY;
+        }
+        if (node.args.length < fn.min || node.args.length > fn.max) {
+            report('arity', arityMessage(node.name, fn), node);
+            return fn.returns(types);
+        }
+        node.args.forEach((arg, index) => {
+            var _a;
+            const expected = fn.params(index);
+            if (!(((_a = types[index]) !== null && _a !== void 0 ? _a : ANY) & expected)) {
+                report('type', `${node.name} expects ${describeTypes(expected)}`, arg);
+            }
+        });
+        const [first, second] = node.args;
+        if (node.name === 'date' && (first === null || first === void 0 ? void 0 : first.kind) === 'string') {
+            const normalized = normalizeDate(first.value);
+            if (normalized === null) {
+                report('type', `'${first.value}' is not an ISO 8601 date`, first);
+            }
+            else {
+                const start = new Date(normalized);
+                analysis.dates.set(node, start);
+                if (DATE_ONLY.test(first.value)) {
+                    analysis.days.set(node, { start, end: new Date(start.getTime() + DAY_MS) });
+                }
+            }
+        }
+        const listed = first ? refColumn(first) : undefined;
+        if (node.name === 'contains' && (listed === null || listed === void 0 ? void 0 : listed.type) === 'multi_select' && second) {
+            if (second.kind === 'string') {
+                resolveOption(second, listed);
+                analysis.memberships.set(node, listed);
+            }
+            else {
+                report('type', `Check '${listed.name}' for an option name`, second);
+            }
+        }
+        const unit = node.args[2];
+        if (DATE_FUNCTIONS.has(node.name) && (unit === null || unit === void 0 ? void 0 : unit.kind) === 'string') {
+            try {
+                parseDateUnit(unit.value, unit.start);
+            }
+            catch (_a) {
+                report('type', `Unknown date unit '${unit.value}'`, unit);
+            }
+        }
+        return fn.returns(types);
+    };
+    const visit = (node) => {
+        const types = visitNode(node);
+        analysis.types.set(node, types);
+        return types;
+    };
+    const visitNode = (node) => {
+        switch (node.kind) {
+            case 'empty':
+                return ANY;
+            case 'number':
+                return NUMBER;
+            case 'string':
+                return STRING;
+            case 'boolean':
+                return BOOLEAN;
+            case 'ref':
+                return visitRef(node);
+            case 'unary': {
+                const operand = visit(node.operand);
+                const operator = { start: node.start, end: node.start + node.operator.length };
+                if (node.operator === 'not') {
+                    if (!(operand & BOOLEAN))
+                        report('type', "Expected a boolean for 'not'", operator);
+                    return BOOLEAN;
+                }
+                if (!(operand & NUMBER))
+                    report('type', `Expected a number for '${node.operator}'`, operator);
+                return NUMBER;
+            }
+            case 'binary':
+                return visitBinary(node);
+            case 'call':
+                return visitCall(node);
+        }
+    };
+    analysis.type = visit(ast);
+    analysis.failed = analysis.diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+    return analysis;
+};
+const sameNode = (left, right) => {
+    if (left === right)
+        return true;
+    if (typeof left !== 'object' || typeof right !== 'object' || !left || !right)
+        return false;
+    const keys = Object.keys(left);
+    if (keys.length !== Object.keys(right).length)
+        return false;
+    return keys.every((key) => sameNode(left[key], right[key]));
+};
+const schemas = new WeakMap();
+export const schemaFor = (columns) => {
+    let schema = schemas.get(columns);
+    if (!schema) {
+        schema = new Schema(columns, analyze);
+        schemas.set(columns, schema);
+    }
+    return schema;
+};
+export const analyzeFor = (ast, columns, columnId) => {
+    var _a;
+    const base = schemaFor(columns);
+    const column = columnId === undefined ? undefined : base.byId.get(columnId);
+    if ((column === null || column === void 0 ? void 0 : column.type) !== 'formula')
+        return { analysis: analyze(ast, base), schema: base, ast };
+    const stored = base.parse(column);
+    const analysis = 'ast' in stored && sameNode(stored.ast, ast) ? base.analysis(column) : undefined;
+    if (analysis && 'ast' in stored)
+        return { analysis, schema: base, ast: stored.ast, stored: column };
+    const schema = base.withExpression(column.id, { ast });
+    return { analysis: (_a = schema.analysis(column)) !== null && _a !== void 0 ? _a : analyze(ast, schema), schema, ast };
+};

package/dist/databases/formula/ast.d.ts

@@ -0,0 +1,52 @@
+export type BinaryOperator = '+' | '-' | '*' | '/' | '%' | '^' | '==' | '!=' | '<' | '<=' | '>' | '>=' | 'and' | 'or';
+export type UnaryOperator = '-' | '+' | 'not';
+export type Span = {
+    start: number;
+    end: number;
+};
+export type FormulaNode = Span & ({
+    kind: 'empty';
+} | {
+    kind: 'number';
+    value: number;
+} | {
+    kind: 'string';
+    value: string;
+} | {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'ref';
+    name: string;
+    id?: string;
+    form: 'bare' | 'prop' | 'id';
+    nameStart: number;
+    nameEnd: number;
+} | {
+    kind: 'unary';
+    operator: UnaryOperator;
+    operand: FormulaNode;
+} | {
+    kind: 'binary';
+    operator: BinaryOperator;
+    operatorStart: number;
+    operatorEnd: number;
+    left: FormulaNode;
+    right: FormulaNode;
+} | {
+    kind: 'call';
+    name: string;
+    args: FormulaNode[];
+});
+export type FormulaRefNode = Extract<FormulaNode, {
+    kind: 'ref';
+}>;
+export type FormulaCallNode = Extract<FormulaNode, {
+    kind: 'call';
+}>;
+export type FormulaBinaryNode = Extract<FormulaNode, {
+    kind: 'binary';
+}>;
+export declare const COMPARISONS: ReadonlySet<BinaryOperator>;
+export declare const childrenOf: (node: FormulaNode) => FormulaNode[];
+export declare const walkFormula: (ast: FormulaNode, visit: (node: FormulaNode) => void) => void;

package/dist/databases/formula/ast.js

@@ -0,0 +1,20 @@
+export const COMPARISONS = new Set(['==', '!=', '<', '<=', '>', '>=']);
+export const childrenOf = (node) => {
+    if (node.kind === 'unary')
+        return [node.operand];
+    if (node.kind === 'binary')
+        return [node.left, node.right];
+    if (node.kind === 'call')
+        return node.args;
+    return [];
+};
+export const walkFormula = (ast, visit) => {
+    const stack = [ast];
+    for (let node = stack.pop(); node; node = stack.pop()) {
+        visit(node);
+        const children = childrenOf(node);
+        for (let index = children.length - 1; index >= 0; index--) {
+            stack.push(children[index]);
+        }
+    }
+};

package/dist/databases/formula/compile.d.ts

@@ -0,0 +1,10 @@
+import { type FormulaNode } from './ast.js';
+import type { FormulaColumn, FormulaRow, FormulaValue } from './types.js';
+export type CompiledFormula = (row: FormulaRow) => FormulaValue;
+export type CompileOptions = {
+    now?: () => Date;
+    columnId?: string;
+};
+export declare const compile: (ast: FormulaNode, columns: readonly FormulaColumn[], options?: CompileOptions) => CompiledFormula;
+export type ColumnPrograms = (columnId: string) => CompiledFormula;
+export declare const compileColumns: (columns: readonly FormulaColumn[], options?: Pick<CompileOptions, 'now'>) => ColumnPrograms;