@mintlify/common 1.0.1310 → 1.0.1312

package/dist/databases/formula/compile.js

@@ -0,0 +1,409 @@
+import { compareCodePoints } from '../query/values.js';
+import { analyzeFor, schemaFor } from './analyze.js';
+import { COMPARISONS, walkFormula, } from './ast.js';
+import { FormulaError, isFormulaError, joinText, toFormulaError } from './errors.js';
+import { expectLogical, getFunction } from './functions.js';
+import { FORMULA_LIMITS } from './limits.js';
+import { cellReader, isEmptyScalar, optionIds } from './values.js';
+const typeOf = (value) => value === null
+    ? 'blank'
+    : value instanceof Date
+        ? 'date'
+        : typeof value === 'string'
+            ? 'text'
+            : typeof value;
+const fail = (message, span, code = 'type') => new FormulaError(code, message, span.start, span.end);
+const settle = (value, span) => {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw fail('Result is not a finite number', span, 'runtime');
+        return value === 0 ? 0 : value;
+    }
+    if (value instanceof Date && Number.isNaN(value.getTime())) {
+        throw fail('Date is out of range', span, 'runtime');
+    }
+    return value;
+};
+const holds = (operator, order) => {
+    switch (operator) {
+        case '==':
+            return order === 0;
+        case '!=':
+            return order !== 0;
+        case '<':
+            return order < 0;
+        case '<=':
+            return order <= 0;
+        case '>':
+            return order > 0;
+        default:
+            return order >= 0;
+    }
+};
+const compareValues = (operator, left, right, span) => {
+    if (isEmptyScalar(left) || isEmptyScalar(right))
+        return operator === '!=';
+    if (typeof left === 'number' && typeof right === 'number') {
+        return holds(operator, Math.sign(left - right));
+    }
+    if (typeof left === 'string' && typeof right === 'string') {
+        return holds(operator, compareCodePoints(left, right));
+    }
+    if (left instanceof Date && right instanceof Date) {
+        return holds(operator, Math.sign(left.getTime() - right.getTime()));
+    }
+    const equality = operator === '==' || operator === '!=';
+    if (typeof left === 'boolean' && typeof right === 'boolean' && equality) {
+        return (left === right) === (operator === '==');
+    }
+    if (equality)
+        return operator === '!=';
+    throw fail(`Cannot compare ${typeOf(left)} and ${typeOf(right)}`, span);
+};
+const MIRRORED = {
+    '==': '==',
+    '!=': '!=',
+    '<': '>',
+    '<=': '>=',
+    '>': '<',
+    '>=': '<=',
+};
+const withinDay = (operator, time, start, end) => {
+    switch (operator) {
+        case '==':
+            return time >= start && time < end;
+        case '!=':
+            return time < start || time >= end;
+        case '<':
+            return time < start;
+        case '<=':
+            return time < end;
+        case '>':
+            return time >= end;
+        default:
+            return time >= start;
+    }
+};
+const arithmetic = (operator, left, right, span) => {
+    switch (operator) {
+        case '-':
+            return left - right;
+        case '*':
+            return left * right;
+        case '/':
+        case '%':
+            if (right === 0)
+                throw fail('Division by zero', span, 'runtime');
+            return operator === '/' ? left / right : left % right;
+        default:
+            return Math.pow(left, right);
+    }
+};
+const sizeOf = (ast) => {
+    let size = 0;
+    walkFormula(ast, () => size++);
+    return size;
+};
+const TOO_COMPLEX = (span) => new FormulaError('too_complex', `Formula too complex: more than ${FORMULA_LIMITS.steps.toLocaleString('en-US')} steps for one row`, span.start, span.end);
+const cacheable = (value) => !isFormulaError(value) || value.code !== 'too_complex';
+class Runtime {
+    constructor(schema, clock) {
+        this.schema = schema;
+        this.programs = new Map();
+        this.pass = { id: 0, steps: 0, at: null };
+        const { pass } = this;
+        this.context = { now: () => { var _a; return ((_a = pass.at) !== null && _a !== void 0 ? _a : (pass.at = clock())); }, text: { used: 0, depth: 0 } };
+    }
+    program(column) {
+        let program = this.programs.get(column.id);
+        if (program)
+            return program;
+        const parsed = this.schema.parse(column);
+        const analysis = this.schema.analysis(column);
+        if ('error' in parsed || !analysis) {
+            const error = 'error' in parsed ? parsed.error : fail('Formula is invalid', parsed.ast);
+            program = () => error;
+        }
+        else {
+            const run = this.build(parsed.ast, analysis);
+            const { pass } = this;
+            if (analysis.volatile) {
+                const memo = new WeakMap();
+                program = (row) => {
+                    const known = memo.get(row);
+                    if ((known === null || known === void 0 ? void 0 : known.pass) === pass.id && this.context.text.depth > 0)
+                        return known.value;
+                    const value = run(row);
+                    if (cacheable(value))
+                        memo.set(row, { pass: pass.id, value });
+                    return value;
+                };
+            }
+            else {
+                const memo = new WeakMap();
+                program = (row) => {
+                    const known = memo.get(row);
+                    if (known !== undefined)
+                        return known;
+                    const value = run(row);
+                    if (cacheable(value))
+                        memo.set(row, value);
+                    return value;
+                };
+            }
+        }
+        this.programs.set(column.id, program);
+        return program;
+    }
+    build(ast, analysis) {
+        const failure = analysis.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+        if (failure)
+            return () => failure;
+        const closure = new Builder(this, analysis).node(ast);
+        const { text } = this.context;
+        const { pass } = this;
+        const size = sizeOf(ast);
+        return (row) => {
+            if (text.depth++ === 0) {
+                text.used = 0;
+                pass.id++;
+                pass.steps = 0;
+                pass.at = null;
+            }
+            try {
+                pass.steps += size;
+                if (pass.steps > FORMULA_LIMITS.steps)
+                    return TOO_COMPLEX(ast);
+                return closure(row);
+            }
+            catch (error) {
+                return toFormulaError(error);
+            }
+            finally {
+                text.depth--;
+            }
+        };
+    }
+}
+class Builder {
+    constructor(runtime, analysis) {
+        this.runtime = runtime;
+        this.analysis = analysis;
+    }
+    node(node) {
+        switch (node.kind) {
+            case 'empty':
+                return () => null;
+            case 'number':
+            case 'string':
+            case 'boolean': {
+                const { value } = node;
+                return () => value;
+            }
+            case 'ref':
+                return this.ref(node);
+            case 'unary': {
+                const operand = this.node(node.operand);
+                if (node.operator === 'not')
+                    return (row) => !expectLogical('not', operand(row), node);
+                const negate = node.operator === '-';
+                return (row) => {
+                    const value = operand(row);
+                    if (value === null)
+                        return null;
+                    if (typeof value !== 'number')
+                        throw fail(`Expected a number for '${node.operator}'`, node);
+                    return settle(negate ? -value : value, node);
+                };
+            }
+            case 'binary':
+                return this.binary(node);
+            case 'call':
+                return this.call(node);
+        }
+    }
+    ref(node) {
+        var _a;
+        const column = this.analysis.columns.get(node);
+        if (!column)
+            throw fail(`Unknown property '${(_a = node.id) !== null && _a !== void 0 ? _a : node.name}'`, node);
+        if (column.type === 'formula') {
+            const program = this.runtime.program(column);
+            return (row) => {
+                const value = program(row);
+                if (!isFormulaError(value))
+                    return value;
+                throw new FormulaError(value.code, `${value.description} in '${column.name}'`, node.start, node.end);
+            };
+        }
+        const read = cellReader(column, this.runtime.schema.optionsOf(column));
+        const { id } = column;
+        return (row) => read(Object.hasOwn(row, id) ? row[id] : undefined);
+    }
+    labels(node) {
+        const column = node.kind === 'ref' ? this.analysis.columns.get(node) : undefined;
+        if ((column === null || column === void 0 ? void 0 : column.type) !== 'multi_select')
+            return undefined;
+        const { id } = column;
+        const { labelById } = this.runtime.schema.optionsOf(column);
+        return (row) => optionIds(Object.hasOwn(row, id) ? row[id] : undefined).map((option) => { var _a; return (_a = labelById.get(option)) !== null && _a !== void 0 ? _a : option; });
+    }
+    operand(node) {
+        const date = this.analysis.dates.get(node);
+        if (date)
+            return () => date;
+        return this.node(node);
+    }
+    compare(node) {
+        var _a;
+        const { operator } = node;
+        const multi = [node.left, node.right].find((side) => { var _a; return side.kind === 'ref' && ((_a = this.analysis.columns.get(side)) === null || _a === void 0 ? void 0 : _a.type) === 'multi_select'; });
+        if (multi) {
+            const read = this.labels(multi);
+            const other = multi === node.left ? node.right : node.left;
+            if (!read || other.kind !== 'string' || other.value === '')
+                return () => false;
+            const label = other.value;
+            return (row) => {
+                const labels = read(row);
+                const has = labels.includes(label);
+                return operator === '==' ? has : !has;
+            };
+        }
+        if ([node.left, node.right].some((side) => side.kind === 'string' && side.value === '')) {
+            return () => false;
+        }
+        const span = { start: node.operatorStart, end: node.operatorEnd };
+        const dayOnRight = this.analysis.days.get(node.right);
+        const day = dayOnRight !== null && dayOnRight !== void 0 ? dayOnRight : this.analysis.days.get(node.left);
+        if (day) {
+            const other = this.operand(dayOnRight ? node.left : node.right);
+            const op = dayOnRight ? operator : ((_a = MIRRORED[operator]) !== null && _a !== void 0 ? _a : operator);
+            const start = day.start.getTime();
+            const end = day.end.getTime();
+            return (row) => {
+                const value = other(row);
+                if (isEmptyScalar(value))
+                    return op === '!=';
+                if (!(value instanceof Date))
+                    throw fail(`Cannot compare ${typeOf(value)} and date`, span);
+                return withinDay(op, value.getTime(), start, end);
+            };
+        }
+        const left = this.operand(node.left);
+        const right = this.operand(node.right);
+        return (row) => compareValues(operator, left(row), right(row), span);
+    }
+    binary(node) {
+        const { operator } = node;
+        if (COMPARISONS.has(operator))
+            return this.compare(node);
+        const left = this.node(node.left);
+        const right = this.node(node.right);
+        const span = { start: node.operatorStart, end: node.operatorEnd };
+        if (operator === 'and') {
+            return (row) => expectLogical('and', left(row), node.left) && expectLogical('and', right(row), node.right);
+        }
+        if (operator === 'or') {
+            return (row) => expectLogical('or', left(row), node.left) || expectLogical('or', right(row), node.right);
+        }
+        if (operator === '+') {
+            return (row) => {
+                const a = left(row);
+                const b = right(row);
+                if (a === null || b === null) {
+                    const other = a !== null && a !== void 0 ? a : b;
+                    if (other === null || typeof other === 'number')
+                        return null;
+                    if (typeof other === 'string')
+                        return other;
+                }
+                if (typeof a === 'number' && typeof b === 'number')
+                    return settle(a + b, span);
+                if (typeof a === 'string' && typeof b === 'string')
+                    return joinText([a, b], span.start, span.end, this.runtime.context.text);
+                throw fail(`Cannot add ${typeOf(a)} and ${typeOf(b)}`, span);
+            };
+        }
+        return (row) => {
+            const a = left(row);
+            const b = right(row);
+            if (a !== null && typeof a !== 'number')
+                throw fail(`Expected a number for '${operator}'`, node.left);
+            if (b !== null && typeof b !== 'number')
+                throw fail(`Expected a number for '${operator}'`, node.right);
+            if (a === null || b === null)
+                return null;
+            return settle(arithmetic(operator, a, b, span), span);
+        };
+    }
+    call(node) {
+        const member = this.analysis.memberships.get(node);
+        const [subject, needle] = node.args;
+        const read = member && subject ? this.labels(subject) : undefined;
+        if (read && (needle === null || needle === void 0 ? void 0 : needle.kind) === 'string') {
+            const label = needle.value;
+            return (row) => read(row).includes(label);
+        }
+        const constant = this.analysis.dates.get(node);
+        if (constant)
+            return () => constant;
+        const fn = getFunction(node.name);
+        if (!fn)
+            throw fail(`Unknown function '${node.name}'`, node);
+        const args = node.args.map((arg) => this.node(arg));
+        const { context } = this.runtime;
+        const { apply } = fn;
+        if (apply)
+            return (row) => settle(apply(args.map((arg) => arg(row)), node, context), node);
+        return (row) => settle(fn.call(args.map((arg) => () => arg(row)), node, context), node);
+    }
+}
+const runtimes = new WeakMap();
+const runtimeFor = (schema, now) => {
+    if (now)
+        return new Runtime(schema, now);
+    let runtime = runtimes.get(schema);
+    if (!runtime) {
+        runtime = new Runtime(schema, () => new Date());
+        runtimes.set(schema, runtime);
+    }
+    return runtime;
+};
+export const compile = (ast, columns, options = {}) => {
+    try {
+        const analyzed = analyzeFor(ast, columns, options.columnId);
+        const runtime = runtimeFor(analyzed.schema, options.now);
+        if (analyzed.stored)
+            return runtime.program(analyzed.stored);
+        return runtime.build(analyzed.ast, analyzed.analysis);
+    }
+    catch (error) {
+        const failure = toFormulaError(error);
+        return () => failure;
+    }
+};
+const programsByColumns = new WeakMap();
+export const compileColumns = (columns, options = {}) => {
+    const shared = options.now ? undefined : programsByColumns.get(columns);
+    if (shared)
+        return shared;
+    const runtime = runtimeFor(schemaFor(columns), options.now);
+    const programs = (columnId) => {
+        const column = runtime.schema.byId.get(columnId);
+        if ((column === null || column === void 0 ? void 0 : column.type) !== 'formula') {
+            const missing = new FormulaError('unknown_property', `Unknown formula property '#${columnId}'`, 0);
+            return () => missing;
+        }
+        try {
+            return runtime.program(column);
+        }
+        catch (error) {
+            const failure = toFormulaError(error);
+            return () => failure;
+        }
+    };
+    if (!options.now)
+        programsByColumns.set(columns, programs);
+    return programs;
+};

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

@@ -0,0 +1,5 @@
+export declare const DATE_UNITS: readonly ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds'];
+export type DateUnit = (typeof DATE_UNITS)[number];
+export declare const parseDateUnit: (unit: string, position: number) => DateUnit;
+export declare const addToDate: (date: Date, amount: number, unit: DateUnit) => Date;
+export declare const dateDifference: (first: Date, second: Date, unit: DateUnit) => number;

package/dist/databases/formula/dates.js

@@ -0,0 +1,55 @@
+import { FormulaError } from './errors.js';
+export const DATE_UNITS = [
+    'years',
+    'months',
+    'weeks',
+    'days',
+    'hours',
+    'minutes',
+    'seconds',
+];
+const UNIT_MS = {
+    weeks: 604800000,
+    days: 86400000,
+    hours: 3600000,
+    minutes: 60000,
+    seconds: 1000,
+};
+export const parseDateUnit = (unit, position) => {
+    const normalized = unit.trim().toLowerCase();
+    const match = DATE_UNITS.find((candidate) => candidate === normalized || candidate === `${normalized}s`);
+    if (!match)
+        throw new FormulaError('type', `Unknown date unit '${unit}'`, position);
+    return match;
+};
+const addMonths = (date, months) => {
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + months;
+    const lastDay = new Date(0);
+    lastDay.setUTCFullYear(year, month + 1, 0);
+    const result = new Date(date.getTime());
+    result.setUTCFullYear(year, month, Math.min(date.getUTCDate(), lastDay.getUTCDate()));
+    return result;
+};
+const monthsBetween = (first, second) => {
+    if (first.getTime() < second.getTime())
+        return -monthsBetween(second, first);
+    const months = (first.getUTCFullYear() - second.getUTCFullYear()) * 12 +
+        first.getUTCMonth() -
+        second.getUTCMonth();
+    return addMonths(second, months).getTime() > first.getTime() ? months - 1 : months;
+};
+export const addToDate = (date, amount, unit) => {
+    if (unit === 'years')
+        return addMonths(date, Math.trunc(amount) * 12);
+    if (unit === 'months')
+        return addMonths(date, Math.trunc(amount));
+    return new Date(date.getTime() + amount * UNIT_MS[unit]);
+};
+export const dateDifference = (first, second, unit) => {
+    if (unit === 'years')
+        return Math.trunc(monthsBetween(first, second) / 12);
+    if (unit === 'months')
+        return monthsBetween(first, second);
+    return Math.trunc((first.getTime() - second.getTime()) / UNIT_MS[unit]);
+};

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

@@ -0,0 +1,18 @@
+export type FormulaErrorCode = 'syntax' | 'too_long' | 'depth' | 'unknown_property' | 'ambiguous_property' | 'unknown_function' | 'arity' | 'type' | 'cycle' | 'dependency' | 'unknown_option' | 'empty_comparison' | 'text_too_large' | 'too_complex' | 'runtime';
+export type FormulaSeverity = 'error' | 'warning';
+export declare class FormulaError extends Error {
+    readonly code: FormulaErrorCode;
+    readonly severity: FormulaSeverity;
+    readonly description: string;
+    readonly start: number;
+    readonly end: number;
+    constructor(code: FormulaErrorCode, description: string, start: number, end?: number, severity?: FormulaSeverity);
+}
+export declare const isFormulaError: (value: unknown) => value is FormulaError;
+export declare const toFormulaError: (error: unknown) => FormulaError;
+export type TextBudget = {
+    used: number;
+    depth: number;
+};
+export declare const joinText: (parts: readonly string[], start: number, end: number, budget: TextBudget) => string;
+export declare const limitText: (text: string, start: number, end: number, budget: TextBudget) => string;

package/dist/databases/formula/errors.js

@@ -0,0 +1,33 @@
+import { FORMULA_LIMITS } from './limits.js';
+export class FormulaError extends Error {
+    constructor(code, description, start, end = start, severity = 'error') {
+        super(`${description} at ${start}`);
+        this.name = 'FormulaError';
+        this.code = code;
+        this.severity = severity;
+        this.description = description;
+        this.start = start;
+        this.end = end;
+    }
+}
+export const isFormulaError = (value) => value instanceof FormulaError;
+export const toFormulaError = (error) => {
+    if (error instanceof FormulaError)
+        return error;
+    if (error instanceof RangeError)
+        return new FormulaError('runtime', 'Formula is too complex', 0);
+    return new FormulaError('runtime', 'Unexpected error', 0);
+};
+const textBytes = (length) => length * 2;
+export const joinText = (parts, start, end, budget) => {
+    const bytes = textBytes(parts.reduce((total, part) => total + part.length, 0));
+    if (bytes > FORMULA_LIMITS.textBytes) {
+        throw new FormulaError('text_too_large', 'Text result exceeds 100 KB', start, end);
+    }
+    budget.used += bytes;
+    if (budget.used > FORMULA_LIMITS.rowTextBytes) {
+        throw new FormulaError('text_too_large', 'Formula builds more than 1 MB of text for this row', start, end);
+    }
+    return parts.join('');
+};
+export const limitText = (text, start, end, budget) => joinText([text], start, end, budget);

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

@@ -0,0 +1,9 @@
+import type { FormulaColumn, FormulaRow } from './types.js';
+export type FormulaFilter = {
+    test: (row: {
+        columns: FormulaRow;
+    }) => boolean;
+} | {
+    error: string;
+};
+export declare const formulaFilterEngine: (source: string, columns: readonly FormulaColumn[]) => FormulaFilter;

package/dist/databases/formula/filter.js

@@ -0,0 +1,16 @@
+import { compile } from './compile.js';
+import { parseFormula } from './parse.js';
+import { typecheck } from './typecheck.js';
+export const formulaFilterEngine = (source, columns) => {
+    const parsed = parseFormula(source);
+    if ('error' in parsed)
+        return { error: parsed.error.message };
+    const { type, diagnostics } = typecheck(parsed.ast, columns);
+    const failure = diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+    if (failure)
+        return { error: failure.message };
+    if (type !== 'boolean')
+        return { error: 'A filter must be true or false' };
+    const run = compile(parsed.ast, columns);
+    return { test: (row) => run(row.columns) === true };
+};

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

@@ -0,0 +1,5 @@
+import type { FormulaNode } from './ast.js';
+export declare const quoteString: (value: string) => string;
+export declare const columnIdReference: (id: string) => string;
+export declare const columnReference: (name: string) => string;
+export declare const formatFormula: (ast: FormulaNode) => string;

package/dist/databases/formula/format.js

@@ -0,0 +1,66 @@
+import { PRECEDENCE } from './parse.js';
+import { isBareName } from './tokenize.js';
+const ESCAPED = {
+    '\\': '\\\\',
+    '"': '\\"',
+    '\n': '\\n',
+    '\r': '\\r',
+    '\t': '\\t',
+};
+export const quoteString = (value) => `"${value.replace(/[\\"\n\r\t]/g, (char) => { var _a; return (_a = ESCAPED[char]) !== null && _a !== void 0 ? _a : char; })}"`;
+export const columnIdReference = (id) => `prop(#${id})`;
+export const columnReference = (name) => isBareName(name) ? name : `prop(${quoteString(name)})`;
+const BINARY_POWER = {
+    or: PRECEDENCE.or,
+    and: PRECEDENCE.and,
+    '==': PRECEDENCE.compare,
+    '!=': PRECEDENCE.compare,
+    '<': PRECEDENCE.compare,
+    '<=': PRECEDENCE.compare,
+    '>': PRECEDENCE.compare,
+    '>=': PRECEDENCE.compare,
+    '+': PRECEDENCE.sum,
+    '-': PRECEDENCE.sum,
+    '*': PRECEDENCE.product,
+    '/': PRECEDENCE.product,
+    '%': PRECEDENCE.product,
+    '^': PRECEDENCE.power,
+};
+const ATOM = 10;
+const powerOf = (node) => {
+    if (node.kind === 'binary')
+        return BINARY_POWER[node.operator];
+    if (node.kind === 'unary')
+        return node.operator === 'not' ? PRECEDENCE.not : PRECEDENCE.sign;
+    return ATOM;
+};
+const formatNode = (node, minPower) => {
+    const text = formatBare(node);
+    return powerOf(node) < minPower ? `(${text})` : text;
+};
+const formatBare = (node) => {
+    switch (node.kind) {
+        case 'empty':
+            return '';
+        case 'number':
+            return String(node.value);
+        case 'string':
+            return quoteString(node.value);
+        case 'boolean':
+            return String(node.value);
+        case 'ref':
+            return node.id === undefined ? columnReference(node.name) : columnIdReference(node.id);
+        case 'unary':
+            return node.operator === 'not'
+                ? `not ${formatNode(node.operand, PRECEDENCE.not)}`
+                : `${node.operator}${formatNode(node.operand, PRECEDENCE.sign)}`;
+        case 'binary': {
+            const power = BINARY_POWER[node.operator];
+            const right = node.operator === '^';
+            return `${formatNode(node.left, right ? power + 1 : power)} ${node.operator} ${formatNode(node.right, right ? power : power + 1)}`;
+        }
+        case 'call':
+            return `${node.name}(${node.args.map((arg) => formatNode(arg, 0)).join(', ')})`;
+    }
+};
+export const formatFormula = (ast) => formatNode(ast, 0);

package/dist/databases/formula/function-docs.d.ts

@@ -0,0 +1,6 @@
+export type FormulaFunctionDoc = {
+    name: string;
+    signature: string;
+    description: string;
+};
+export declare const FORMULA_FUNCTIONS: readonly FormulaFunctionDoc[];