@doist/todoist-sdk 15.1.0 → 15.2.0

package/dist/esm/utils/filter-queries.js

@@ -0,0 +1,231 @@
+import { FILTER_QUERY_DATE_TOKENS, FILTER_QUERY_LANGUAGES, FILTER_QUERY_OPERATOR_TOKENS, FILTER_QUERY_PATTERNS, FILTER_QUERY_TOKENS, } from './filter-query-definitions.js';
+const DEFAULT_LANGUAGE = 'en';
+const DATE_TOKENS = new Set(FILTER_QUERY_DATE_TOKENS);
+const OPERATOR_TOKENS = new Set(FILTER_QUERY_OPERATOR_TOKENS);
+/** Operators are the same symbols in every language, and they end a bare date. */
+const OPERATOR_PATTERN = /[()!&|]/;
+/**
+ * Deepest run of parentheses this reads before giving up.
+ *
+ * Parentheses are the only construct left that recurses, and Todoist caps a
+ * saved query long before this. The limit is what keeps a hostile string from
+ * reaching the call stack.
+ */
+const MAX_NESTING_DEPTH = 100;
+/** Codes the parser answers to beyond the language names themselves. */
+const LANGUAGE_ALIASES = new Map([
+    ['zh-cn', 'zh_cn'],
+    ['zh-hans', 'zh_cn'],
+    ['zh_hans', 'zh_cn'],
+    ['zh-tw', 'zh_tw'],
+    ['zh-hant', 'zh_tw'],
+    ['zh_hant', 'zh_tw'],
+]);
+const MATCHERS_BY_LANGUAGE = new Map();
+function lookUpLanguage(code) {
+    var _a;
+    return ((_a = LANGUAGE_ALIASES.get(code)) !== null && _a !== void 0 ? _a : FILTER_QUERY_LANGUAGES.find((language) => language === code));
+}
+function resolveLanguage(lang) {
+    var _a, _b;
+    if (!lang)
+        return DEFAULT_LANGUAGE;
+    const code = lang.toLowerCase();
+    return (_b = (_a = lookUpLanguage(code)) !== null && _a !== void 0 ? _a : lookUpLanguage(code.split(/[-_]/)[0])) !== null && _b !== void 0 ? _b : DEFAULT_LANGUAGE;
+}
+function createMatchers(language) {
+    const patterns = FILTER_QUERY_PATTERNS[language];
+    const matchers = [];
+    for (const token of FILTER_QUERY_TOKENS) {
+        for (const pattern of patterns[token]) {
+            matchers.push({
+                token,
+                length: pattern.length,
+                regex: new RegExp(`\\s*${pattern}\\s*`, 'iuy'),
+            });
+        }
+    }
+    // Longest pattern first, as the engine does. Otherwise `all` claims the
+    // front of Dutch's `alles bekijken` and the rest reads as a date.
+    return matchers.sort((a, b) => b.length - a.length);
+}
+function matchersFor(language) {
+    const cached = MATCHERS_BY_LANGUAGE.get(language);
+    if (cached)
+        return cached;
+    const matchers = createMatchers(language);
+    MATCHERS_BY_LANGUAGE.set(language, matchers);
+    return matchers;
+}
+function matchAt(query, cursor, matchers) {
+    for (const matcher of matchers) {
+        matcher.regex.lastIndex = cursor;
+        if (matcher.regex.test(query) && matcher.regex.lastIndex > cursor) {
+            return { token: matcher.token, end: matcher.regex.lastIndex };
+        }
+    }
+    return null;
+}
+/**
+ * Splits a query on unescaped commas, the way Todoist does before parsing.
+ * Each part is drawn as its own list.
+ */
+function splitSubqueries(query) {
+    const subqueries = [];
+    let current = '';
+    let escaped = false;
+    for (let index = 0; index < query.length; index += 1) {
+        const character = query[index];
+        if (character === ',' && !escaped) {
+            subqueries.push(current);
+            current = '';
+            continue;
+        }
+        current += character;
+        escaped = !escaped && character === '\\';
+    }
+    subqueries.push(current);
+    return subqueries.map((subquery) => subquery.trim()).filter((subquery) => subquery.length > 0);
+}
+/**
+ * Reads a subquery into tokens.
+ *
+ * Anything the vocabulary doesn't claim is a bare date: the engine tries every
+ * keyword first and hands what is left to its date parser, which is what reads
+ * `today`, `hoy` and `2026-12-24`. A bare date runs to the next operator.
+ */
+function tokenize(subquery, matchers) {
+    const tokens = [];
+    let cursor = 0;
+    while (cursor < subquery.length) {
+        const match = matchAt(subquery, cursor, matchers);
+        if (match) {
+            tokens.push(match.token);
+            cursor = match.end;
+            continue;
+        }
+        const offset = subquery.slice(cursor + 1).search(OPERATOR_PATTERN);
+        tokens.push('BARE_DATE');
+        cursor = offset === -1 ? subquery.length : cursor + 1 + offset;
+    }
+    return tokens;
+}
+function peek(reader) {
+    return reader.index < reader.tokens.length ? reader.tokens[reader.index] : undefined;
+}
+function next(reader) {
+    const token = peek(reader);
+    reader.index += 1;
+    return token;
+}
+/**
+ * `<expression 4> ::= <expression 3> [ or <expression 4> ]`
+ *
+ * The engine nests this to the right and folds with a minimum, so reading the
+ * chain in a loop lands on the same grouping without a frame per operator.
+ */
+function readOr(reader) {
+    let grouping = readAnd(reader);
+    while (grouping !== null && peek(reader) === 'OR') {
+        next(reader);
+        const right = readAnd(reader);
+        if (right === null)
+            return null;
+        // `|` keeps the lower grouping, so one flat side flattens the pair.
+        grouping = grouping === 'DAY' && right === 'DAY' ? 'DAY' : 'FLAT';
+    }
+    return grouping;
+}
+/** `<expression 3> ::= <expression 2> [ and <expression 3> ]` */
+function readAnd(reader) {
+    let grouping = readNot(reader);
+    while (grouping !== null && peek(reader) === 'AND') {
+        next(reader);
+        const right = readNot(reader);
+        if (right === null)
+            return null;
+        // `&` keeps the higher grouping, so one dated side leads the pair.
+        grouping = grouping === 'DAY' || right === 'DAY' ? 'DAY' : 'FLAT';
+    }
+    return grouping;
+}
+/** `<expression 2> ::= { [ not ] <expression 2> } | <expression 1>` */
+function readNot(reader) {
+    let negated = false;
+    while (peek(reader) === 'NOT') {
+        next(reader);
+        negated = true;
+    }
+    const grouping = readOperand(reader);
+    if (grouping === null)
+        return null;
+    // A negation never groups by day, however the expression under it reads.
+    return negated ? 'FLAT' : grouping;
+}
+/** `<expression 1> ::= { "(" <expression> ")" } | <query>` */
+function readOperand(reader) {
+    const token = next(reader);
+    if (token === undefined)
+        return null;
+    if (token === 'LEFT') {
+        if (reader.depth >= MAX_NESTING_DEPTH)
+            return null;
+        reader.depth += 1;
+        const grouping = readOr(reader);
+        reader.depth -= 1;
+        if (grouping === null || next(reader) !== 'RIGHT')
+            return null;
+        return grouping;
+    }
+    if (token === 'BARE_DATE')
+        return 'DAY';
+    if (OPERATOR_TOKENS.has(token))
+        return null;
+    return DATE_TOKENS.has(token) ? 'DAY' : 'FLAT';
+}
+function groupingOf(subquery, matchers) {
+    const reader = { tokens: tokenize(subquery, matchers), index: 0, depth: 0 };
+    const grouping = readOr(reader);
+    // Tokens left over mean the query doesn't parse, which the engine rejects.
+    return grouping !== null && reader.index === reader.tokens.length ? grouping : null;
+}
+/**
+ * Returns whether a filter query leads with dates rather than with priority.
+ *
+ * Todoist gives every filter one of two default hierarchies, and a query that
+ * mentions dates gets the date-first one. Pass the answer to {@link sortTasks}
+ * as its `defaultOrder`:
+ *
+ * ```ts
+ * sortTasks(tasks, {
+ *     sortedBy: savedOptions?.sortedBy,
+ *     sortOrder: savedOptions?.sortOrder,
+ *     defaultOrder: isDateDrivenQuery(query, { lang }) ? 'DATE_FIRST' : 'PRIORITY_FIRST',
+ * })
+ * ```
+ *
+ * The query is read in `lang`, the account language `getUser` returns, the way
+ * the API reads it. English keywords parse under every language, so `lang` only
+ * matters for a query written in the account's own: `sin fecha` is a keyword
+ * under `es` and an unreadable phrase under `en`.
+ *
+ * Commas divide a filter into subqueries and Todoist draws each one as its own
+ * list, with its own hierarchy. Classify them one at a time for exact results;
+ * a whole query answers true only when every subquery is date-driven.
+ *
+ * Two kinds of unreadable query part company here. One that breaks the grammar,
+ * such as `(today`, returns false. One that only breaks the vocabulary, such as
+ * `sin fecha` under `en`, returns true, because a word this package doesn't
+ * recognize is treated as a bare date. Pass the account's own `lang` and the
+ * question doesn't arise; get it wrong and a keyword can read as a date.
+ *
+ * The function performs no I/O.
+ *
+ * @see sortTasks
+ */
+export function isDateDrivenQuery(query, options = {}) {
+    const matchers = matchersFor(resolveLanguage(options.lang));
+    const subqueries = splitSubqueries(query);
+    return (subqueries.length > 0 &&
+        subqueries.every((subquery) => groupingOf(subquery, matchers) === 'DAY'));
+}