@lakutata/entrypoint 3.0.0-beta.0

package/dist/esm/lib/pattern/GlobPattern.js

@@ -0,0 +1,64 @@
+/*
+ * The glob matching of the values of the patterns, rewritten from gex (Copyright (c) 2011-2020 Richard Rodger, MIT
+ * License, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * A glob of the value of a pattern: "*" matches any characters, "?" one character, "**" is a literal "*" and "*?" a
+ * literal "?". It matches a whole value, converted to a string
+ */
+export class GlobPattern {
+    /**
+     * The expression of the glob, undefined when it matches nothing (no glob)
+     */
+    #expression;
+    /**
+     * Whether a value of a pattern is a glob
+     * @param value
+     */
+    static isGlob(value) {
+        return /[*?]/.test(value);
+    }
+    /**
+     * @param glob the glob, nothing is matched without it
+     */
+    constructor(glob) {
+        this.glob = glob;
+        //NaN is the empty glob, as gex cleans it
+        this.#expression = glob === null || glob === undefined ? undefined : GlobPattern.expression(Number.isNaN(glob) ? '' : String(glob));
+    }
+    /**
+     * The regular expression of a glob
+     * @param glob
+     */
+    static expression(glob) {
+        let source = glob.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
+        //[\s\S] matches the line feeds too
+        source = source.replace(/\\\*/g, '[\\s\\S]*');
+        source = source.replace(/\\\?/g, '[\\s\\S]');
+        //"**" and "*?" are the literal "*" and "?"
+        source = source.replace(/\[\\s\\S\]\*\[\\s\\S\]\*/g, '\\*');
+        source = source.replace(/\[\\s\\S\]\*\[\\s\\S\]/g, '\\?');
+        return new RegExp(`^${source}$`);
+    }
+    /**
+     * Whether the glob matches a value converted to a string
+     * @param value
+     */
+    test(value) {
+        return !!this.#expression && this.#expression.test(String(value));
+    }
+    /**
+     * Whether the glob matches the value of a subject: a missing value is not matched, a primitive value (a date, a
+     * regular expression) is matched as a string. An array or an object is always matched, as gex does (it gives back
+     * the collection of its matching elements, which is never null): the routing of the actions is the one of 2.x
+     * @param value
+     */
+    matches(value) {
+        if (value === null || value === undefined)
+            return false;
+        const type = typeof value;
+        if (type === 'string' || type === 'number' || type === 'boolean' || value instanceof Date || value instanceof RegExp)
+            return this.test(value);
+        return true;
+    }
+}

package/dist/esm/lib/pattern/PatternManager.js

@@ -0,0 +1,229 @@
+/*
+ * The matching of the patterns, rewritten from patrun (Copyright (c) 2013-2022 Richard Rodger, MIT License, see
+ * THIRD_PARTY_NOTICES.md): the same decision tree, the same results
+ */
+import { GlobPattern } from './GlobPattern.js';
+/**
+ * A dictionary without prototype: the values of the subjects are never the properties of Object ("constructor"…)
+ */
+function dictionary() {
+    return Object.create(null);
+}
+/**
+ * The patterns of the actions and the objects they give: a subject is matched by the most specific pattern whose
+ * properties it has (the unknown properties of the subject are ignored)
+ */
+export class PatternManager {
+    #globMatch;
+    #top = {};
+    constructor(options = { globMatch: true }) {
+        this.#globMatch = !!options.globMatch;
+    }
+    /**
+     * The glob of a value of a pattern, undefined when it is not one
+     * @param value
+     */
+    glob(value) {
+        return this.#globMatch && GlobPattern.isGlob(value) ? new GlobPattern(value) : undefined;
+    }
+    /**
+     * The node of a glob of a key of a node, added once
+     * @param node
+     * @param key
+     * @param glob
+     */
+    globNode(node, key, glob) {
+        const globs = node.globs ??= dictionary();
+        const branches = globs[key] ??= [];
+        let branch = branches.find((candidate) => candidate.glob.glob === glob.glob);
+        if (!branch)
+            branches.push(branch = { glob: glob, node: {} });
+        return branch.node;
+    }
+    /**
+     * Register a pattern, and the object that will be returned if an input matches.
+     * Both keys and values are considered to be strings.
+     * Other types are converted to strings.
+     * @param pattern
+     * @param obj
+     */
+    add(pattern, obj) {
+        const keys = Object.keys(pattern).filter((key) => pattern[key] !== null && pattern[key] !== undefined).sort();
+        const values = Object.fromEntries(keys.map((key) => [key, String(pattern[key])]));
+        let node = this.#top;
+        //The keys of the path are ordered: a key is inserted before the next key of the path, or follows the star nodes
+        for (let index = 0; index < keys.length; index++) {
+            const key = keys[index];
+            const value = values[key];
+            const glob = this.glob(value);
+            if (node.values && node.key === key) {
+                //The key of the node
+                node = glob ? this.globNode(node, key, glob) : node.values[value] ??= {};
+            }
+            else if (!node.key) {
+                //The end of the path: the key is the last one
+                node.key = key;
+                node.values = dictionary();
+                node = glob ? this.globNode(node, key, glob) : node.values[value] = {};
+            }
+            else if (key < node.key) {
+                //The key orders before the key of the node: the node moves to the star node of the key
+                const { star, globs } = node;
+                node.star = { key: node.key, values: node.values };
+                if (star)
+                    node.star.star = star;
+                if (globs)
+                    node.star.globs = globs;
+                if (node.globs)
+                    node.globs = dictionary();
+                node.key = key;
+                node.values = dictionary();
+                node = glob ? this.globNode(node, key, glob) : node.values[value] = {};
+            }
+            else {
+                //The key orders after the key of the node: it is in the path of the patterns without the key of the node
+                node = node.star ??= {};
+                index--;
+            }
+        }
+        if (obj !== undefined) {
+            node.data = obj;
+            node.hasData = true;
+        }
+        return this;
+    }
+    /**
+     * Remove this pattern, and it's object, from the matcher.
+     * @param pattern
+     */
+    remove(pattern) {
+        let node = this.#top;
+        let data = undefined;
+        let hasData = false;
+        let last = undefined;
+        do {
+            const key = node.key;
+            if (node.values || node.globs) {
+                let next = node.values?.[pattern[key]];
+                if (next)
+                    last = next;
+                if (!next && node.globs) {
+                    const branch = (node.globs[key] ?? []).find((candidate) => candidate.glob.glob === pattern[key]);
+                    if (branch)
+                        last = next = branch.node;
+                }
+                if (next) {
+                    data = next.data;
+                    hasData = !!next.hasData;
+                    node = next;
+                }
+                else {
+                    node = node.star;
+                }
+            }
+            else {
+                node = undefined;
+            }
+        } while (node);
+        if (hasData && data !== undefined && last) {
+            delete last.data;
+            delete last.hasData;
+        }
+        return this;
+    }
+    /**
+     * Return the unique match for this subject, or null if not found.
+     * The properties of the subject are matched against the patterns previously added, and the most specifc pattern wins.
+     * Unknown properties in the subject are ignored.
+     * If exact is true, then all properties of the subject must match.
+     * @param subject
+     * @param exact
+     */
+    find(subject, exact = false) {
+        if (subject === null || subject === undefined)
+            return null;
+        const top = this.#top;
+        let node = top;
+        let data = top.hasData ? top.data : null;
+        const stars = [];
+        const found = exact ? new Set() : undefined;
+        do {
+            const key = node.key;
+            if (node.values) {
+                const value = subject[key];
+                //The value itself (converted to a string, as the key of a dictionary), else a glob of it
+                let next = node.values[value];
+                if (!next && node.globs?.[key])
+                    next = node.globs[key].find((branch) => branch.glob.matches(value))?.node;
+                if (next) {
+                    found?.add(key);
+                    if (node.star)
+                        stars.push(node.star);
+                    data = next.hasData ? next.data : (exact ? null : data);
+                    node = next;
+                }
+                else {
+                    //The patterns without the key
+                    node = node.star;
+                }
+            }
+            else {
+                node = undefined;
+            }
+            //The wider patterns, when the narrower ones gave nothing
+            if (!node && stars.length && (data === null || data === undefined))
+                node = stars.pop();
+        } while (node);
+        if (exact) {
+            if (found.size !== Object.keys(subject).length)
+                data = null;
+        }
+        else if ((data === null || data === undefined) && top.hasData) {
+            //The object of the empty pattern matches everything
+            data = top.data;
+        }
+        return data;
+    }
+    /**
+     * Return the list of registered patterns that contain this partial pattern.
+     * You can use wildcards for property values.
+     * Omitted values are not equivalent to a wildcard of "*", you must specify each property explicitly.
+     * @param partialPattern
+     * @param exact the omitted properties match nothing
+     */
+    list(partialPattern, exact = false) {
+        const pattern = partialPattern ?? {};
+        const results = [];
+        const descend = (node, match, missing) => {
+            if (!node.values)
+                return;
+            const key = node.key;
+            const glob = new GlobPattern(pattern[key] === null || pattern[key] === undefined ? (exact ? null : '*') : pattern[key]);
+            for (const value in node.values) {
+                //The empty value is not matched by a glob (gex gives back the matched value, which is falsy)
+                if (value === pattern[key] || (!exact && (pattern[key] === null || pattern[key] === undefined)) || (value !== '' && glob.test(value))) {
+                    const valueMatch = { ...match, [key]: value };
+                    const valueMissing = { ...missing };
+                    delete valueMissing[key];
+                    const next = node.values[value];
+                    if (!Object.keys(valueMissing).length && next.hasData && next.data)
+                        results.push({ match: valueMatch, data: next.data });
+                    if (next.values)
+                        descend(next, { ...valueMatch }, { ...valueMissing });
+                }
+            }
+            if (node.star)
+                descend(node.star, { ...match }, { ...missing });
+        };
+        if (this.#top.hasData && this.#top.data)
+            results.push({ match: {}, data: this.#top.data });
+        descend(this.#top, {}, { ...pattern });
+        return results;
+    }
+    /**
+     * Generate a string representation of the decision tree for debugging.
+     */
+    toJSON() {
+        return JSON.stringify(this.#top, (key, value) => value instanceof GlobPattern ? String(value.glob) : (key === 'hasData' ? undefined : value));
+    }
+}

package/dist/esm/lib/schedule/Cron.js

@@ -0,0 +1,277 @@
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const WEEKDAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+const MACROS = {
+    '@yearly': '0 0 0 1 1 *',
+    '@annually': '0 0 0 1 1 *',
+    '@monthly': '0 0 0 1 * *',
+    '@weekly': '0 0 0 * * 0',
+    '@daily': '0 0 0 * * *',
+    '@midnight': '0 0 0 * * *',
+    '@hourly': '0 0 * * * *'
+};
+/**
+ * The formatters of the time zones
+ */
+const formatters = new Map();
+/**
+ * The wall clock time of an instant, in a time zone or in the local time
+ * @param time
+ * @param timezone
+ */
+function wallClock(time, timezone) {
+    if (!timezone) {
+        const date = new Date(time);
+        return {
+            year: date.getFullYear(),
+            month: date.getMonth() + 1,
+            day: date.getDate(),
+            hour: date.getHours(),
+            minute: date.getMinutes(),
+            second: date.getSeconds(),
+            weekday: date.getDay()
+        };
+    }
+    let formatter = formatters.get(timezone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+            weekday: 'short'
+        });
+        formatters.set(timezone, formatter);
+    }
+    const parts = {};
+    for (const part of formatter.formatToParts(new Date(time)))
+        parts[part.type] = part.value;
+    return {
+        year: Number(parts.year),
+        month: Number(parts.month),
+        day: Number(parts.day),
+        hour: Number(parts.hour),
+        minute: Number(parts.minute),
+        second: Number(parts.second),
+        weekday: WEEKDAYS.indexOf(parts.weekday.toLowerCase())
+    };
+}
+/**
+ * A wall clock time as a number, to compare them
+ * @param clock
+ */
+function wallKey(clock) {
+    return Date.UTC(clock.year, clock.month - 1, clock.day, clock.hour, clock.minute, clock.second);
+}
+/**
+ * The instant of a wall clock time (the overflowing fields carry over), in a time zone or in the local time
+ * @param year
+ * @param month
+ * @param day
+ * @param hour
+ * @param minute
+ * @param second
+ * @param timezone
+ */
+function instant(year, month, day, hour, minute, second, timezone) {
+    if (!timezone)
+        return new Date(year, month - 1, day, hour, minute, second).getTime();
+    const wall = Date.UTC(year, month - 1, day, hour, minute, second);
+    //The offset of the time zone at the instant, found again at the corrected instant (the offset changes with the daylight saving time)
+    let time = wall;
+    for (let pass = 0; pass < 2; pass++) {
+        const clock = wallClock(time, timezone);
+        const offset = Date.UTC(clock.year, clock.month - 1, clock.day, clock.hour, clock.minute, clock.second) - time;
+        time = wall - offset;
+    }
+    return time;
+}
+/**
+ * Parse a field of an expression
+ * @param text
+ * @param min
+ * @param max
+ * @param names the names of the values from min
+ * @param expression
+ */
+function parseField(text, min, max, names, expression) {
+    const invalid = (reason) => new SyntaxError(`Invalid cron expression "${expression}": ${reason}`);
+    const value = (item) => {
+        const index = names ? names.indexOf(item.toLowerCase()) : -1;
+        const parsed = index >= 0 ? index + min : /^\d+$/.test(item) ? Number(item) : NaN;
+        if (Number.isNaN(parsed) || parsed < min || parsed > max)
+            throw invalid(`"${item}" is not a value from ${min} to ${max}`);
+        return parsed;
+    };
+    const values = new Set();
+    const restricted = text !== '*' && text !== '?';
+    for (const item of text.split(',')) {
+        const [range, stepText] = item.split('/');
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            throw invalid(`"${stepText}" is not a step`);
+        let start = min;
+        let end = max;
+        if (range !== '*' && range !== '?') {
+            const [from, to] = range.split('-');
+            start = value(from);
+            end = to === undefined ? (stepText === undefined ? start : max) : value(to);
+            if (end < start)
+                throw invalid(`the range "${range}" is reversed`);
+        }
+        for (let current = start; current <= end; current += step)
+            values.add(current);
+    }
+    return { values: values, restricted: restricted };
+}
+/**
+ * A cron expression, as `@Schedule` uses it: `second minute hour day-of-month month day-of-week`, the second optional
+ * (0 when omitted). Each field accepts `*` (or `?`), values, ranges (`1-5`), steps (`*\/15`, `10/5`, `1-30/2`) and lists
+ * (`1,15`); the months and the days of the week also accept their English three-letter names (`jan`, `mon`), and the
+ * day of the week 7 is Sunday like 0. The macros `@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight`
+ * and `@hourly` are accepted. When both the day of the month and the day of the week are restricted, a day matching
+ * either of them matches.
+ * @example
+ * ```typescript
+ * import {Cron} from 'lakutata/com/entrypoint'
+ *
+ * //At 09:30 on the weekdays, in Shanghai
+ * const cron: Cron = new Cron('30 9 * * mon-fri', 'Asia/Shanghai')
+ * const next: Date | undefined = cron.next(new Date('2026-01-02T12:00:00Z'))
+ * console.log(next?.toISOString()) //2026-01-05T01:30:00.000Z
+ * console.log(new Cron('0 0 30 2 *').next()) //undefined: February has no 30th
+ * ```
+ */
+export class Cron {
+    #second;
+    #minute;
+    #hour;
+    #day;
+    #month;
+    #weekday;
+    /**
+     * Parse a cron expression.
+     * @param expression The expression, 5 or 6 fields separated by spaces, or a macro (case-insensitive).
+     * @param timezone The IANA time zone the expression's times are in (`Asia/Shanghai`); the local time zone when
+     * omitted.
+     * @throws {SyntaxError} When the expression does not have 5 or 6 fields, or a field has a value out of its range,
+     * a reversed range or an invalid step.
+     * @throws {RangeError} When the time zone is unknown.
+     */
+    constructor(expression, timezone) {
+        this.expression = expression;
+        this.timezone = timezone;
+        if (timezone)
+            new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+        const normalized = expression.trim().toLowerCase();
+        const fields = (MACROS[normalized] ?? normalized).split(/\s+/);
+        if (fields.length === 5)
+            fields.unshift('0');
+        if (fields.length !== 6)
+            throw new SyntaxError(`Invalid cron expression "${expression}": 5 or 6 fields are expected`);
+        this.#second = parseField(fields[0], 0, 59, undefined, expression);
+        this.#minute = parseField(fields[1], 0, 59, undefined, expression);
+        this.#hour = parseField(fields[2], 0, 23, undefined, expression);
+        this.#day = parseField(fields[3], 1, 31, undefined, expression);
+        this.#month = parseField(fields[4], 1, 12, MONTHS, expression);
+        const weekday = parseField(fields[5], 0, 7, WEEKDAYS, expression);
+        //7 is Sunday too
+        if (weekday.values.delete(7))
+            weekday.values.add(0);
+        this.#weekday = weekday;
+    }
+    /**
+     * Whether a day matches
+     * @param clock
+     */
+    #dayMatches(clock) {
+        const day = this.#day.values.has(clock.day);
+        const weekday = this.#weekday.values.has(clock.weekday);
+        if (this.#day.restricted && this.#weekday.restricted)
+            return day || weekday;
+        return day && weekday;
+    }
+    /**
+     * Find the next time matching the expression, strictly after a time, to the second. When the clocks go back, the
+     * times of the repeated hour match once; the times skipped when the clocks go forward never match.
+     * @param after The time to search from, a date or milliseconds since the epoch; now by default.
+     * @returns The next matching time, `undefined` when none matches within eight years (such as February 30th).
+     */
+    next(after = Date.now()) {
+        const timezone = this.timezone;
+        const start = Math.floor(new Date(after).getTime() / 1000) * 1000;
+        //When the clocks go back, the times of the repeated hour match once
+        const afterKey = wallKey(wallClock(start, timezone));
+        let time = start + 1000;
+        //Eight years of candidates at most: a leap day on a weekday comes back within them
+        const limit = time + 8 * 366 * 24 * 3600 * 1000;
+        while (time < limit) {
+            const clock = wallClock(time, timezone);
+            let candidate;
+            if (!this.#month.values.has(clock.month)) {
+                candidate = instant(clock.year, clock.month + 1, 1, 0, 0, 0, timezone);
+            }
+            else if (!this.#dayMatches(clock)) {
+                candidate = instant(clock.year, clock.month, clock.day + 1, 0, 0, 0, timezone);
+            }
+            else if (!this.#hour.values.has(clock.hour)) {
+                candidate = instant(clock.year, clock.month, clock.day, clock.hour + 1, 0, 0, timezone);
+            }
+            else if (!this.#minute.values.has(clock.minute)) {
+                candidate = instant(clock.year, clock.month, clock.day, clock.hour, clock.minute + 1, 0, timezone);
+            }
+            else if (!this.#second.values.has(clock.second)) {
+                candidate = instant(clock.year, clock.month, clock.day, clock.hour, clock.minute, clock.second + 1, timezone);
+            }
+            else if (wallKey(clock) <= afterKey) {
+                candidate = time + (afterKey - wallKey(clock)) + 1000;
+            }
+            else {
+                return new Date(time);
+            }
+            //A time skipped by the daylight saving time may map back: the search always moves forward
+            time = candidate > time ? candidate : time + 1000;
+        }
+        return undefined;
+    }
+}
+/**
+ * Parse a duration into milliseconds, as `@Schedule` reads its intervals.
+ * @param duration A number of milliseconds, or a text of numbers with their units (`ms`, `s`, `m`, `h`, `d`), summed
+ * and case-insensitive: `500ms`, `30s`, `1.5h`, `1h 30m`, `1d`.
+ * @returns The duration in milliseconds.
+ * @throws {SyntaxError} When the duration is not positive (or not finite), or the text has an unknown part.
+ * @example
+ * ```typescript
+ * import {parseDuration} from 'lakutata/com/entrypoint'
+ *
+ * console.log(parseDuration('1h30m')) //5400000
+ * console.log(parseDuration('500ms')) //500
+ * console.log(parseDuration(2000)) //2000
+ * ```
+ */
+export function parseDuration(duration) {
+    if (typeof duration === 'number') {
+        if (!Number.isFinite(duration) || duration <= 0)
+            throw new SyntaxError(`Invalid duration ${duration}: a positive number of milliseconds is expected`);
+        return duration;
+    }
+    const units = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    const text = duration.trim().toLowerCase();
+    let total = 0;
+    let rest = text;
+    const part = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)/;
+    while (rest) {
+        const matched = part.exec(rest);
+        if (!matched)
+            throw new SyntaxError(`Invalid duration "${duration}": such as "500ms", "30s", "5m", "1h30m" or "1d"`);
+        total += Number(matched[1]) * units[matched[2]];
+        rest = rest.slice(matched[0].length).trim();
+    }
+    if (total <= 0)
+        throw new SyntaxError(`Invalid duration "${duration}": it must be positive`);
+    return total;
+}

package/dist/esm/types/CLIContextParams.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/ErrorDescription.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/HTTPContextParams.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/ScheduleContextParams.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/ServiceContextParams.js

@@ -0,0 +1 @@
+export {};