@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/seed/words.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The words `tablewalk seed` makes rows from. Small on purpose: enough that
+ * forty customers do not share a name, few enough to read in one sitting, and
+ * no dependency to install (`npx tablewalk` has no build step). Every name is
+ * made up; every address is example.com, which no mail ever reaches; every
+ * phone number is in 555-01xx, the range kept for fiction.
+ */
+export declare const FIRST: string[];
+export declare const LAST: string[];
+export declare const COMPANY_FIRST: string[];
+export declare const COMPANY_LAST: string[];
+export declare const COMPANY_SUFFIX: string[];
+export declare const CITIES: string[];
+export declare const STATES: string[];
+export declare const STREETS: string[];
+export declare const THING_ADJ: string[];
+export declare const THING: string[];
+export declare const MAKES: string[];
+export declare const MODELS: string[];
+export declare const COLORS: string[];
+export declare const PRIORITY_WEIGHT: Record<string, number>;

package/dist/server/seed/words.js

@@ -0,0 +1,164 @@
+/**
+ * The words `tablewalk seed` makes rows from. Small on purpose: enough that
+ * forty customers do not share a name, few enough to read in one sitting, and
+ * no dependency to install (`npx tablewalk` has no build step). Every name is
+ * made up; every address is example.com, which no mail ever reaches; every
+ * phone number is in 555-01xx, the range kept for fiction.
+ */
+export const FIRST = [
+    'Ada',
+    'Amara',
+    'Ben',
+    'Carmen',
+    'Chen',
+    'Dana',
+    'Diego',
+    'Elena',
+    'Eli',
+    'Farah',
+    'Grace',
+    'Hana',
+    'Ivan',
+    'Jade',
+    'Jonah',
+    'Kai',
+    'Lena',
+    'Leo',
+    'Maya',
+    'Marcus',
+    'Nadia',
+    'Noah',
+    'Omar',
+    'Priya',
+    'Quinn',
+    'Rosa',
+    'Sam',
+    'Sofia',
+    'Tariq',
+    'Tess',
+    'Uma',
+    'Victor',
+    'Wren',
+    'Yusuf',
+    'Zoe',
+    'Ruth',
+    'Owen',
+    'Iris',
+    'Hugo',
+    'Mei',
+];
+export const LAST = [
+    'Abbott',
+    'Alvarez',
+    'Bennett',
+    'Brooks',
+    'Castillo',
+    'Chandler',
+    'Dawson',
+    'Delgado',
+    'Ellis',
+    'Fischer',
+    'Foster',
+    'Garcia',
+    'Hale',
+    'Hayes',
+    'Ibarra',
+    'Jensen',
+    'Kaur',
+    'Keller',
+    'Lam',
+    'Larsen',
+    'Mendez',
+    'Morgan',
+    'Nakamura',
+    'Novak',
+    'Okafor',
+    'Ortega',
+    'Patel',
+    'Price',
+    'Quinlan',
+    'Reyes',
+    'Rossi',
+    'Santos',
+    'Shaw',
+    'Tanaka',
+    'Turner',
+    'Underwood',
+    'Vance',
+    'Walsh',
+    'Webb',
+    'Young',
+];
+/* A company is two of these and a suffix: Harbor Supply Co., Northwind Labs. */
+export const COMPANY_FIRST = [
+    'Harbor',
+    'Northwind',
+    'Bluebird',
+    'Cedar',
+    'Copper',
+    'Granite',
+    'Juniper',
+    'Lakeside',
+    'Maple',
+    'Meridian',
+    'Oakline',
+    'Pinecrest',
+    'Redwood',
+    'Riverbend',
+    'Silverline',
+    'Summit',
+    'Sunrise',
+    'Tidewater',
+    'Westfield',
+    'Willow',
+];
+export const COMPANY_LAST = ['Supply', 'Labs', 'Works', 'Partners', 'Group', 'Logistics', 'Studio', 'Foods', 'Health', 'Systems'];
+export const COMPANY_SUFFIX = ['Co.', 'Inc.', 'LLC', ''];
+export const CITIES = [
+    'Springfield',
+    'Riverton',
+    'Fairview',
+    'Greenville',
+    'Madison',
+    'Franklin',
+    'Clinton',
+    'Georgetown',
+    'Salem',
+    'Arlington',
+    'Ashland',
+    'Oxford',
+    'Milton',
+    'Dover',
+    'Hudson',
+];
+export const STATES = ['CA', 'NY', 'TX', 'WA', 'OR', 'IL', 'MA', 'CO', 'GA', 'NC'];
+export const STREETS = ['Main St', 'Oak Ave', 'Maple Dr', 'Cedar Ln', 'Park Rd', 'Elm St', 'Lake View', 'Hill St', 'Pine Ct', 'Mill Rd'];
+/* Things: a part, a product, an item — "Compact filter", "Heavy-duty bracket". */
+export const THING_ADJ = ['Standard', 'Compact', 'Heavy-duty', 'Premium', 'Basic', 'Pro', 'Classic', 'Light', 'Large', 'Small'];
+export const THING = [
+    'bracket',
+    'cable',
+    'filter',
+    'seal',
+    'bearing',
+    'valve',
+    'panel',
+    'sensor',
+    'tire',
+    'chain',
+    'belt',
+    'lamp',
+    'clamp',
+    'hose',
+    'pad set',
+    'kit',
+    'mount',
+    'switch',
+    'spring',
+    'grip',
+];
+/* A make and a model, for something people own and bring in: Halden Ridge 3. */
+export const MAKES = ['Halden', 'Corvo', 'Brightline', 'Marlowe', 'Ostra', 'Vantor', 'Kestrel', 'Larkspur'];
+export const MODELS = ['Ridge', 'Tempo', 'Atlas', 'Drift', 'Summit', 'Metro', 'Trail', 'Vista', 'Comet', 'Arc'];
+export const COLORS = ['Black', 'White', 'Red', 'Blue', 'Green', 'Silver', 'Orange', 'Gray', 'Yellow', 'Teal'];
+export const PRIORITY_WEIGHT = { low: 3, normal: 5, medium: 5, high: 2, urgent: 1, critical: 1 };

package/dist/server/serverRequests.d.ts

@@ -0,0 +1,6 @@
+/** Mark a request, or a write's values, as the server's own. */
+export declare function serverRequest<T extends object>(request: T): T;
+/** Whether a request — or a write's `values`, which an upload's file columns are marked on — is the server's own. */
+export declare function isServerRequest(request: unknown): boolean;
+/** A layer that copies a request (a tenant lease's captured data) carries the server's mark to its copy. */
+export declare function carryServerRequest<T>(from: unknown, to: T): T;

package/dist/server/serverRequests.js

@@ -0,0 +1,33 @@
+/**
+ * The requests the server builds for its own work on a file (http/fileRows.ts,
+ * an upload's values, files/fileStorage.ts placeFile): the only ones that may
+ * name an `internal` column — a file's object and hash — which the access
+ * guard (app/appAccess.ts resourceChecks) refuses to every other request, read or
+ * write. A WeakSet of the objects themselves, so nothing that arrives as data —
+ * JSON, a copy, a request rebuilt from one — is ever in it.
+ */
+const serverRequests = new WeakSet();
+/** Mark a request, or a write's values, as the server's own. */
+export function serverRequest(request) {
+    serverRequests.add(request);
+    return request;
+}
+/** Whether a request — or a write's `values`, which an upload's file columns are marked on — is the server's own. */
+export function isServerRequest(request) {
+    if (typeof request !== 'object' || request === null)
+        return false;
+    if (serverRequests.has(request))
+        return true;
+    const values = request.values;
+    return typeof values === 'object' && values !== null && serverRequests.has(values);
+}
+/** A layer that copies a request (a tenant lease's captured data) carries the server's mark to its copy. */
+export function carryServerRequest(from, to) {
+    if (isServerRequest(from) && typeof to === 'object' && to !== null) {
+        serverRequests.add(to);
+        const values = to.values;
+        if (typeof values === 'object' && values !== null)
+            serverRequests.add(values);
+    }
+    return to;
+}

package/dist/server/serverTimeouts.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The timeouts every tablewalk HTTP server sets, in one place.
+ *
+ * Keep-alive outlives the idle timeouts of the proxies tablewalk is deployed
+ * behind: nginx and cloud load balancers hold an idle upstream connection
+ * for about a minute. At Node's five-second default the server closed a
+ * pooled socket just as a proxy or client reused it, and that request failed
+ * with a reset. The headers timeout stays above keep-alive, as Node requires,
+ * and still bounds a client that sends its headers slowly; the request
+ * timeout bounds a whole body. A socket that takes over a minute for its
+ * headers, or ten for its body, is not a browser on this tool: cheap where
+ * the server is loopback, the whole defence where someone bound it wider.
+ *
+ * The long keep-alive has a cost at shutdown. `close()` drops the sockets idle
+ * at that moment, but a response still being written when it ran finishes
+ * with `Connection: keep-alive`, and its socket then idles for the full
+ * sixty-five seconds while `close()` waits on it — a browser left open on the
+ * page held a stopping server for a minute. So once `close()` has run, the
+ * idle sockets are swept again every quarter second until the server has
+ * closed. A sweep rather than a `request` listener: the tenant and flag
+ * servers wrap the one listener a server has, and refuse a second.
+ *
+ * Node counts a socket that has not sent a byte as busy, not idle, so the
+ * sweep closes those too: a browser opens a spare connection ahead of a
+ * request it may never make, and holds it about ten seconds before giving up,
+ * which held a stopping suite past a test's whole timeout. One silent for a
+ * second has asked nothing, so nothing is lost; a younger one may be a
+ * request still on its way, and is left to send it.
+ */
+import type { Server } from 'node:http';
+export declare const KEEP_ALIVE_TIMEOUT_MS = 65000;
+export declare const HEADERS_TIMEOUT_MS = 66000;
+export declare function applyServerTimeouts(server: Server): Server;

package/dist/server/serverTimeouts.js

@@ -0,0 +1,32 @@
+export const KEEP_ALIVE_TIMEOUT_MS = 65_000;
+export const HEADERS_TIMEOUT_MS = 66_000;
+const REQUEST_TIMEOUT_MS = 600_000;
+const CLOSE_SWEEP_MS = 250;
+const SILENT_MS = 1_000;
+export function applyServerTimeouts(server) {
+    server.keepAliveTimeout = KEEP_ALIVE_TIMEOUT_MS;
+    server.headersTimeout = HEADERS_TIMEOUT_MS;
+    server.requestTimeout = REQUEST_TIMEOUT_MS;
+    /* Each socket by when it connected: one silent past a second is a spare, not a request still on its way. */
+    const sockets = new Map();
+    server.on('connection', (socket) => {
+        sockets.set(socket, Date.now());
+        socket.once('close', () => sockets.delete(socket));
+    });
+    const close = server.close;
+    server.close = function closeAndSweep(callback) {
+        const unused = () => {
+            for (const [socket, connected] of sockets)
+                if (socket.bytesRead === 0 && Date.now() - connected > SILENT_MS)
+                    socket.destroy();
+        };
+        const sweep = setInterval(() => {
+            server.closeIdleConnections();
+            unused();
+        }, CLOSE_SWEEP_MS);
+        sweep.unref();
+        server.once('close', () => clearInterval(sweep));
+        return close.call(this, callback);
+    };
+    return server;
+}

package/dist/server/shapeonly.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A connection that hands out shape and never rows.
+ *
+ * The README's boundary — "rows entering an agent's context leave the
+ * machine, so point it at development databases" — was a sentence asking to
+ * be believed. `"rows": false` makes it a property of the connection: the
+ * catalog, the counts, the lint and the plans still answer, and every path
+ * that would return a value from a row refuses.
+ *
+ * Enforced by wrapping the adapter rather than by checking at each endpoint.
+ * There are eight endpoints and fifteen tools today and there will be more,
+ * and a rule spelled out in eighteen places is a rule with a hole in it. The
+ * wrapper is the choke point every read already goes through, so a feature
+ * added later inherits the boundary instead of having to remember it.
+ *
+ * What still answers is deliberate: shape is what an agent is here for. Which
+ * tables exist, what points at what, how many rows there are, how much of a
+ * column is null, what a statement's plan looks like. What it cannot have is
+ * a value out of a row — including the ones `profile` reports, since a
+ * minimum, a maximum and the most common values are row content however
+ * aggregated.
+ */
+import { type Adapter } from '../adapters/adapter.js';
+/**
+ * The same adapter with every row-returning method refused.
+ *
+ * Methods are copied rather than proxied through a Proxy so that the optional
+ * ones stay honestly absent: an adapter with no `runSql` must still look like
+ * an adapter with no `runSql`, or callers that check for it before offering
+ * SQL start offering it and failing.
+ */
+export declare function shapeOnly(adapter: Adapter, name: string): Adapter;

package/dist/server/shapeonly.js

@@ -0,0 +1,110 @@
+/**
+ * A connection that hands out shape and never rows.
+ *
+ * The README's boundary — "rows entering an agent's context leave the
+ * machine, so point it at development databases" — was a sentence asking to
+ * be believed. `"rows": false` makes it a property of the connection: the
+ * catalog, the counts, the lint and the plans still answer, and every path
+ * that would return a value from a row refuses.
+ *
+ * Enforced by wrapping the adapter rather than by checking at each endpoint.
+ * There are eight endpoints and fifteen tools today and there will be more,
+ * and a rule spelled out in eighteen places is a rule with a hole in it. The
+ * wrapper is the choke point every read already goes through, so a feature
+ * added later inherits the boundary instead of having to remember it.
+ *
+ * What still answers is deliberate: shape is what an agent is here for. Which
+ * tables exist, what points at what, how many rows there are, how much of a
+ * column is null, what a statement's plan looks like. What it cannot have is
+ * a value out of a row — including the ones `profile` reports, since a
+ * minimum, a maximum and the most common values are row content however
+ * aggregated.
+ */
+import { Refusal } from '../adapters/adapter.js';
+import { configFileName } from './product.js';
+const why = (name, what) => new Refusal(`"${name}" is shape-only: ${what} would return data out of its rows. ` +
+    'The catalog, row counts, null fractions, plans and lint still answer. ' +
+    `Remove "rows": false from its entry in your ${configFileName()} to read rows from it.`);
+/**
+ * The same adapter with every row-returning method refused.
+ *
+ * Methods are copied rather than proxied through a Proxy so that the optional
+ * ones stay honestly absent: an adapter with no `runSql` must still look like
+ * an adapter with no `runSql`, or callers that check for it before offering
+ * SQL start offering it and failing.
+ */
+export function shapeOnly(adapter, name) {
+    const wrapped = Object.create(Object.getPrototypeOf(adapter));
+    Object.assign(wrapped, adapter);
+    /* Bound to the original: the copies above are the original's methods, and
+       calling them on `wrapped` would work by accident on a plain object and
+       break on a class instance holding private state. */
+    const from = (key) => {
+        const method = adapter[key];
+        return typeof method === 'function' ? method.bind(adapter) : undefined;
+    };
+    wrapped.introspect = from('introspect');
+    wrapped.close = from('close');
+    wrapped.count = from('count');
+    /* Pool meters are counts and durations about connections, never a value
+       out of a row; bound like the rest, so they read the original's pools. */
+    if (adapter.poolStats)
+        wrapped.poolStats = from('poolStats');
+    wrapped.query = () => {
+        throw why(name, 'reading rows');
+    };
+    if (adapter.runSql)
+        wrapped.runSql = () => {
+            throw why(name, 'running SQL');
+        };
+    if (adapter.runView)
+        wrapped.runView = () => {
+            throw why(name, 'running a view');
+        };
+    if (adapter.countView)
+        wrapped.countView = from('countView');
+    if (adapter.insert)
+        wrapped.insert = () => {
+            throw why(name, 'inserting');
+        };
+    if (adapter.update)
+        wrapped.update = () => {
+            throw why(name, 'updating');
+        };
+    if (adapter.remove)
+        wrapped.remove = () => {
+            throw why(name, 'deleting');
+        };
+    /* A transaction hands out `insert` and `remove` of its own, from inside the
+       adapter, where the refusals above cannot reach them. Refused whole. */
+    if (adapter.transaction)
+        wrapped.transaction = () => {
+            throw why(name, 'writing');
+        };
+    /* A breakdown's group keys *are* row values — `by status` answers with the
+       statuses. The counts beside them would be safe and are not worth the
+       surface: an answer with its labels blanked is not an answer. Counting the
+       groups is a cardinality fact and stays, for the same reason `profile`
+       keeps its distinct count. */
+    if (adapter.runBreakdown)
+        wrapped.runBreakdown = () => {
+            throw why(name, 'grouping rows');
+        };
+    if (adapter.countBreakdown)
+        wrapped.countBreakdown = from('countBreakdown');
+    /* Profile keeps the numbers and loses the values. "52% null, 4,100
+       distinct" is the fact that decides a LEFT join and carries nothing out
+       of any row; a minimum, a maximum and the most common values carry rows. */
+    if (adapter.profile) {
+        const profile = from('profile');
+        wrapped.profile = async (table, limits) => {
+            const result = await profile(table, limits);
+            return {
+                ...result,
+                columns: result.columns.map(({ min, max, common, ...rest }) => rest),
+                redacted: 'Values withheld: this connection is shape-only.',
+            };
+        };
+    }
+    return wrapped;
+}

package/dist/server/startupWarnings.d.ts

@@ -0,0 +1,32 @@
+type EmitWarning = typeof process.emitWarning;
+/** Installed once, before anything imports `node:sqlite`. */
+export declare function quietSqliteExperimentalWarning(target?: {
+    emitWarning: EmitWarning;
+}): void;
+/**
+ * The oldest Node a start accepts: the major `engines` names in package.json, and the one CI, the image and the
+ * desktop app run. npm only warns on `engines`, and `npx` not even that, so on an older Node the first anyone heard
+ * was a missing export or a syntax error from somewhere inside the server. One line before any of it is loaded says
+ * what is wrong instead.
+ */
+export declare const NODE_FLOOR = 24;
+/** What a start on `version` (process.versions.node) prints before it refuses, or undefined when it is new enough. */
+export declare function oldNodeRefusal(version?: string): string | undefined;
+/** Print `line` once per process, however many Apps or handlers reach it. */
+export declare function warnOnce(key: string, line: string, write?: (line: string) => void): void;
+/**
+ * Sign-in served beyond this machine at an `http:` public address: the session cookies are marked Secure only when
+ * the address the server answers to is https, so here they never are, and a browser sends them over plain http too.
+ * Said when the operator has chosen to serve it anyway (`--insecure-http-sign-in`); otherwise it is refused
+ * (`insecureSignInRefusal`).
+ */
+export declare function insecureCookieWarning(publicUrl: string, listenHost: string): string | undefined;
+/** What a start with sign-in on that same condition is refused with: passwords would cross the network in the clear. */
+export declare function insecureSignInRefusal(publicUrl: string, listenHost: string): string | undefined;
+/** The one line a served App writes when a reset was requested and nothing can send it: no link, no token, no address. */
+export declare const resetWithoutMailLog: () => string;
+/** A served App that offers password reset (MISTRI_AUTH_RESET=log) with no email service: the offer cannot be kept. */
+export declare const RESET_WITHOUT_MAIL_WARNING: string;
+/** A fetch-style host that names no client: every visitor is one address to the sign-in and form rate limits. */
+export declare const SHARED_RATE_LIMIT_WARNING: string;
+export {};

package/dist/server/startupWarnings.js

@@ -0,0 +1,92 @@
+/**
+ * Node's ExperimentalWarning for `node:sqlite`, kept off a start's output.
+ *
+ * tablewalk opens `node:sqlite` whatever the connections are — its own stores
+ * (sign-in, API tokens, a tenant's journal) are SQLite files — so the Node
+ * releases that still call the module experimental printed "SQLite is an
+ * experimental feature" on every start, above a config that names only
+ * PostgreSQL. It is a note about Node's API to whoever chose to use it, and
+ * that is this package, which pins the Node versions it supports: the person
+ * running tablewalk can do nothing with it. Only that one warning is dropped;
+ * every other goes out as Node would send it.
+ */
+import { envName, product } from './product.js';
+const isSqliteExperimental = (warning, type) => {
+    const name = warning instanceof Error ? warning.name : typeof type === 'string' ? type : type?.type;
+    const message = warning instanceof Error ? warning.message : String(warning);
+    return name === 'ExperimentalWarning' && /\bSQLite\b/i.test(message);
+};
+/** Installed once, before anything imports `node:sqlite`. */
+export function quietSqliteExperimentalWarning(target = process) {
+    const emit = target.emitWarning;
+    target.emitWarning = function emitWarning(warning, ...rest) {
+        if (isSqliteExperimental(warning, rest[0]))
+            return;
+        return emit.call(this ?? target, warning, ...rest);
+    };
+}
+/**
+ * The oldest Node a start accepts: the major `engines` names in package.json, and the one CI, the image and the
+ * desktop app run. npm only warns on `engines`, and `npx` not even that, so on an older Node the first anyone heard
+ * was a missing export or a syntax error from somewhere inside the server. One line before any of it is loaded says
+ * what is wrong instead.
+ */
+export const NODE_FLOOR = 24;
+/** What a start on `version` (process.versions.node) prints before it refuses, or undefined when it is new enough. */
+export function oldNodeRefusal(version = process.versions.node) {
+    if (Number(version.split('.')[0]) >= NODE_FLOOR)
+        return undefined;
+    return `${product()} needs Node ${NODE_FLOOR} or newer; this is Node ${version}. Install Node ${NODE_FLOOR} (https://nodejs.org) and run it again.`;
+}
+const said = new Set();
+/** Print `line` once per process, however many Apps or handlers reach it. */
+export function warnOnce(key, line, write = console.warn) {
+    if (said.has(key))
+        return;
+    said.add(key);
+    write(`${product()}: warning: ${line}`);
+}
+const LOOPBACK = /^(localhost|127\.\d+\.\d+\.\d+|::1|\[::1\])$/i;
+/** The public address when sign-in is served beyond this machine at an `http:` one, else undefined. */
+function insecureOrigin(publicUrl, listenHost) {
+    let url;
+    try {
+        url = new URL(publicUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== 'http:' || (LOOPBACK.test(listenHost) && LOOPBACK.test(url.hostname)))
+        return undefined;
+    return url.origin;
+}
+/**
+ * Sign-in served beyond this machine at an `http:` public address: the session cookies are marked Secure only when
+ * the address the server answers to is https, so here they never are, and a browser sends them over plain http too.
+ * Said when the operator has chosen to serve it anyway (`--insecure-http-sign-in`); otherwise it is refused
+ * (`insecureSignInRefusal`).
+ */
+export function insecureCookieWarning(publicUrl, listenHost) {
+    const origin = insecureOrigin(publicUrl, listenHost);
+    if (!origin)
+        return undefined;
+    return (`sign-in is served beyond this machine at ${origin}, an http address, so its session cookies are never marked Secure. ` +
+        `Serve it behind a TLS proxy and set its public address (${envName('PUBLIC_URL')}) to the proxy's https address.`);
+}
+/** What a start with sign-in on that same condition is refused with: passwords would cross the network in the clear. */
+export function insecureSignInRefusal(publicUrl, listenHost) {
+    const origin = insecureOrigin(publicUrl, listenHost);
+    if (!origin)
+        return undefined;
+    return (`sign-in would be served beyond this machine at ${origin}, an http address: passwords and session cookies would cross the network in the clear. ` +
+        `Set the public address (${envName('PUBLIC_URL')}) to the https address of a TLS proxy in front, or listen on loopback (--host 127.0.0.1) behind it. ` +
+        `To serve it over plain http anyway, pass --insecure-http-sign-in (${envName('INSECURE_HTTP_SIGN_IN')}=1).`);
+}
+/** The one line a served App writes when a reset was requested and nothing can send it: no link, no token, no address. */
+export const resetWithoutMailLog = () => `${product()}: a password reset was requested but no mail transport is configured, so nothing was sent.`;
+/** A served App that offers password reset (MISTRI_AUTH_RESET=log) with no email service: the offer cannot be kept. */
+export const RESET_WITHOUT_MAIL_WARNING = 'password reset is offered (MISTRI_AUTH_RESET=log) but no email service is configured, so a reset request sends nothing and ' +
+    'the link is never written to the log outside `mistri dev`. Name an email service in the config file, or unset MISTRI_AUTH_RESET.';
+/** A fetch-style host that names no client: every visitor is one address to the sign-in and form rate limits. */
+export const SHARED_RATE_LIMIT_WARNING = 'the fetch handler was called without a clientAddress, so every visitor shares one sign-in rate limit and lockout. ' +
+    "Pass the visitor's address as the second argument: tw.fetch(request, { clientAddress }).";

package/dist/shared/addressParams.d.ts

@@ -0,0 +1,28 @@
+/** A tab label's existing address spelling; shared without client state. */
+export declare function tabSlug(label: string): string;
+/** A tab's word in an address: the App's own language's, whatever language its label is said in. */
+export declare const tabKey: (tab: {
+    label: string;
+    slug?: string;
+}) => string;
+/** A record tab's word in an address: a section group's name, a related list's title. */
+export declare function tabWord(token: string): string;
+/** Whether a tab token is the one an address's word names. */
+export declare const tabMatches: (token: string, asked: string | undefined) => boolean;
+export declare function addressFilterValue(raw: string): {
+    kind: 'values';
+    values: string[];
+} | {
+    kind: 'range';
+    min?: string;
+    max?: string;
+} | undefined;
+/** Undefined means the whole sort is outside this grammar. Preserve the
+ * browser's existing identifier spelling, duplicate fields and ordering;
+ * an API consumer must apply its own declared-field and ambiguity checks. */
+export declare function addressSortValue(raw: string): {
+    field: string;
+    descending: boolean;
+}[] | undefined;
+/** All time, said where a dashboard opens on a window of its own (`window: 'last 30 days'`): `?period=all-time`. */
+export declare const ALL_TIME = "all-time";

package/dist/shared/addressParams.js

@@ -0,0 +1,47 @@
+/** Data-only lexical pieces of the existing browser list address grammar.
+ * These helpers do not authorize fields, coerce schema values or validate an
+ * API request. Callers own parameter uniqueness, limits and refusal policy.
+ * Numeric lexemes remain text so large integers are never rounded here. */
+import { slug as slugOf } from './slug.js';
+/** A tab label's existing address spelling; shared without client state. */
+export function tabSlug(label) {
+    return label
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** A tab's word in an address: the App's own language's, whatever language its label is said in. */
+export const tabKey = (tab) => tab.slug ?? tabSlug(tab.label);
+/** A record tab's word in an address: a section group's name, a related list's title. */
+export function tabWord(token) {
+    if (token.startsWith('tab:'))
+        return slugOf(token.slice(4), token);
+    if (token.startsWith('section:'))
+        return `section-${token.slice(8)}`;
+    return slugOf(token, token);
+}
+/** Whether a tab token is the one an address's word names. */
+export const tabMatches = (token, asked) => asked !== undefined && (token === asked || tabWord(token) === asked);
+export function addressFilterValue(raw) {
+    if (!raw.trim())
+        return undefined;
+    const range = /^(-?\d+(?:\.\d+)?)?\.\.(-?\d+(?:\.\d+)?)?$/.exec(raw.trim());
+    if (range && (range[1] || range[2]))
+        return { kind: 'range', ...(range[1] ? { min: range[1] } : {}), ...(range[2] ? { max: range[2] } : {}) };
+    const values = raw
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+    return values.length ? { kind: 'values', values } : undefined;
+}
+/** Undefined means the whole sort is outside this grammar. Preserve the
+ * browser's existing identifier spelling, duplicate fields and ordering;
+ * an API consumer must apply its own declared-field and ambiguity checks. */
+export function addressSortValue(raw) {
+    if (!/^-?[A-Za-z_][\w.]*(,-?[A-Za-z_][\w.]*)*$/.test(raw))
+        return undefined;
+    return raw.split(',').map((field) => ({ field: field.startsWith('-') ? field.slice(1) : field, descending: field.startsWith('-') }));
+}
+/** All time, said where a dashboard opens on a window of its own (`window: 'last 30 days'`): `?period=all-time`. */
+export const ALL_TIME = 'all-time';