@orthacms/utils-server 0.4.2 → 0.4.3

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { parseFilterTree } from './lib/filters/parse-filter-tree';
 export { applyFilterTree, type ApplyFilterTreeOptions, type FilterExtensionResolver } from './lib/filters/tree-to-drizzle';
 export type { DbLike, TableLike } from './lib/filters/table-helpers';
-export { FilterOperator, ScalarFieldType, RelationKind } from './lib/filters/types';
+export { FilterOperator, ScalarFieldType, RelationKind, WithinLastUnit } from './lib/filters/types';
 export { OPERATORS_BY_TYPE, operatorsFor } from './lib/filters/operator-support';
-export type { ScalarFieldSchema, FieldSchema, RelationSchema, RelationScope, FilterSchema, ParsedRule, ParsedGroup, ParsedNode } from './lib/filters/types';
+export type { WithinLastValue, ScalarFieldSchema, FieldSchema, RelationSchema, RelationScope, FilterSchema, ParsedRule, ParsedGroup, ParsedNode } from './lib/filters/types';
 export { FilterException, FilterErrorCode, FilterSchemaException } from './lib/filters/filter-exceptions';
 export { clampInt } from './lib/clamp-int';
 export { isForeignKeyViolation, isUniqueViolation, violatedConstraint } from './lib/pg-errors';
+export { readEnv, requireEnv, readPositiveInt, readOptionalPositiveInt, readList, readOptionalList, readFlag, readTrustProxy, readNodeEnv, isProduction, when, defined, NODE_ENVS, type NodeEnv } from './lib/env';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EACH,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACH,cAAc,EACd,eAAe,EACf,YAAY,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACf,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACR,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,eAAe,EACf,eAAe,EACf,qBAAqB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EACrB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EACH,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACH,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACf,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACR,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,eAAe,EACf,eAAe,EACf,qBAAqB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACH,OAAO,EACP,UAAU,EACV,eAAe,EACf,uBAAuB,EACvB,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,EACP,SAAS,EACT,KAAK,OAAO,EACf,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.violatedConstraint = exports.isUniqueViolation = exports.isForeignKeyViolation = exports.clampInt = exports.FilterSchemaException = exports.FilterErrorCode = exports.FilterException = exports.operatorsFor = exports.OPERATORS_BY_TYPE = exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = exports.applyFilterTree = exports.parseFilterTree = void 0;
+exports.NODE_ENVS = exports.defined = exports.when = exports.isProduction = exports.readNodeEnv = exports.readTrustProxy = exports.readFlag = exports.readOptionalList = exports.readList = exports.readOptionalPositiveInt = exports.readPositiveInt = exports.requireEnv = exports.readEnv = exports.violatedConstraint = exports.isUniqueViolation = exports.isForeignKeyViolation = exports.clampInt = exports.FilterSchemaException = exports.FilterErrorCode = exports.FilterException = exports.operatorsFor = exports.OPERATORS_BY_TYPE = exports.WithinLastUnit = exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = exports.applyFilterTree = exports.parseFilterTree = void 0;
 var parse_filter_tree_1 = require("./lib/filters/parse-filter-tree");
 Object.defineProperty(exports, "parseFilterTree", { enumerable: true, get: function () { return parse_filter_tree_1.parseFilterTree; } });
 var tree_to_drizzle_1 = require("./lib/filters/tree-to-drizzle");
@@ -9,6 +9,7 @@ var types_1 = require("./lib/filters/types");
 Object.defineProperty(exports, "FilterOperator", { enumerable: true, get: function () { return types_1.FilterOperator; } });
 Object.defineProperty(exports, "ScalarFieldType", { enumerable: true, get: function () { return types_1.ScalarFieldType; } });
 Object.defineProperty(exports, "RelationKind", { enumerable: true, get: function () { return types_1.RelationKind; } });
+Object.defineProperty(exports, "WithinLastUnit", { enumerable: true, get: function () { return types_1.WithinLastUnit; } });
 var operator_support_1 = require("./lib/filters/operator-support");
 Object.defineProperty(exports, "OPERATORS_BY_TYPE", { enumerable: true, get: function () { return operator_support_1.OPERATORS_BY_TYPE; } });
 Object.defineProperty(exports, "operatorsFor", { enumerable: true, get: function () { return operator_support_1.operatorsFor; } });
@@ -22,3 +23,17 @@ var pg_errors_1 = require("./lib/pg-errors");
 Object.defineProperty(exports, "isForeignKeyViolation", { enumerable: true, get: function () { return pg_errors_1.isForeignKeyViolation; } });
 Object.defineProperty(exports, "isUniqueViolation", { enumerable: true, get: function () { return pg_errors_1.isUniqueViolation; } });
 Object.defineProperty(exports, "violatedConstraint", { enumerable: true, get: function () { return pg_errors_1.violatedConstraint; } });
+var env_1 = require("./lib/env");
+Object.defineProperty(exports, "readEnv", { enumerable: true, get: function () { return env_1.readEnv; } });
+Object.defineProperty(exports, "requireEnv", { enumerable: true, get: function () { return env_1.requireEnv; } });
+Object.defineProperty(exports, "readPositiveInt", { enumerable: true, get: function () { return env_1.readPositiveInt; } });
+Object.defineProperty(exports, "readOptionalPositiveInt", { enumerable: true, get: function () { return env_1.readOptionalPositiveInt; } });
+Object.defineProperty(exports, "readList", { enumerable: true, get: function () { return env_1.readList; } });
+Object.defineProperty(exports, "readOptionalList", { enumerable: true, get: function () { return env_1.readOptionalList; } });
+Object.defineProperty(exports, "readFlag", { enumerable: true, get: function () { return env_1.readFlag; } });
+Object.defineProperty(exports, "readTrustProxy", { enumerable: true, get: function () { return env_1.readTrustProxy; } });
+Object.defineProperty(exports, "readNodeEnv", { enumerable: true, get: function () { return env_1.readNodeEnv; } });
+Object.defineProperty(exports, "isProduction", { enumerable: true, get: function () { return env_1.isProduction; } });
+Object.defineProperty(exports, "when", { enumerable: true, get: function () { return env_1.when; } });
+Object.defineProperty(exports, "defined", { enumerable: true, get: function () { return env_1.defined; } });
+Object.defineProperty(exports, "NODE_ENVS", { enumerable: true, get: function () { return env_1.NODE_ENVS; } });

package/dist/lib/env.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Reading `process.env` into typed configuration.
+ *
+ * A host's `ortha.config.ts` is the one file allowed to touch the environment,
+ * and every deployment writes the same handful of readers to do it: a required
+ * string, a bounded number, a comma list, `TRUST_PROXY`, `NODE_ENV`. They were
+ * duplicated between this repo's host and the scaffolder's template, where the
+ * copies had already drifted — the template's number reader had no
+ * "optional, no default" form, so a generated app could not express a ceiling
+ * that means "leave the plugin's own default alone".
+ *
+ * Every reader here **throws rather than guesses**. That is the whole point of
+ * the module: the failure mode of environment parsing is silence, and a config
+ * value that is quietly wrong is discovered a session TTL later, or by reading
+ * a `Set-Cookie` header, rather than at boot with the variable named.
+ *
+ * The last two exports — {@link when} and {@link defined} — read nothing. They
+ * are here because they are what a host does with the readers' `undefined`:
+ * plugins merge their settings as `{ ...DEFAULTS, ...config }`, so an unset
+ * value must become an *absent key* rather than an explicit `undefined`, which
+ * would erase the default it was meant to leave alone. Every host writing that
+ * as `...(x ? { key } : {})` at each call site is the duplication this module
+ * exists to end.
+ */
+/**
+ * A trimmed environment value, `undefined` when unset **or empty**.
+ *
+ * The one reader every other reader here is built on, so "empty means not
+ * configured" is decided once. That equivalence matters: `.env.example` ships
+ * keys with no value, and `ANTHROPIC_API_KEY=` has to leave a deployment with
+ * *no* Claude backend rather than one registered with an empty key — a backend
+ * that is in the picker and fails on the first message.
+ */
+export declare function readEnv(name: string): string | undefined;
+/**
+ * Reads a value the app cannot run without, failing at load rather than
+ * several seconds into boot.
+ *
+ * Left to default to `''`, a missing `DATABASE_URL` reaches `pg` as "use the
+ * libpq defaults", and the first thing that touches the database fails with
+ * whatever the local libpq environment happens to produce (measured: `SASL:
+ * SCRAM-SERVER-FIRST-MESSAGE: client password must be a string`). The server
+ * does fail closed, which is the important half, but nothing in that message
+ * names the variable that was never set.
+ *
+ * @param name The environment variable to read.
+ * @param hint Appended to the error, for a deployment-specific instruction —
+ *   which file to copy, which secret store to look in. Omitted, the message
+ *   says only that there is no usable default.
+ */
+export declare function requireEnv(name: string, hint?: string): string;
+/**
+ * Reads a numeric setting: the default when unset or empty, the value when it
+ * is a plain positive decimal integer, and an error otherwise.
+ *
+ * This replaces `Number(process.env[x]) || default`, which was wrong in three
+ * directions at once and silent in all of them. `0` is falsy, so it became the
+ * default — `LOGIN_RATE_LIMIT=0` ("block every login") quietly meant 10. A
+ * negative is truthy, so it was accepted — `SESSION_TTL_SECONDS=-1` issued
+ * every session already expired, login answering `201` and the very next
+ * request `401`. And exponent notation parsed, so `GRAPHQL_MAX_DEPTH=1e9`
+ * removed the cost budget that ADR-0008 calls GraphQL's replacement for REST's
+ * structural bound. Refusing to boot names the variable; the alternative was a
+ * deployment that looked configured and was not.
+ *
+ * Empty is deliberately *not* an error: `.env.example` ships several keys with
+ * no value, and a fresh clone must boot from it unchanged.
+ */
+export declare function readPositiveInt(name: string, fallback: number): number;
+/**
+ * As {@link readPositiveInt}, but `undefined` when unset — no default to fall
+ * back to.
+ *
+ * The form a *ceiling* needs. A plugin that ships its own default cannot be
+ * handed `{ maxSteps: undefined }`, because spreading that overwrites the
+ * default with nothing; the caller conditionally spreads on this instead.
+ */
+export declare function readOptionalPositiveInt(name: string): number | undefined;
+/**
+ * A comma-separated list setting, trimmed and emptied of blanks.
+ *
+ * An explicitly empty value yields an empty list rather than the fallback,
+ * because "allow no origins" is a setting somebody means.
+ */
+export declare function readList(name: string, fallback: string): string[];
+/**
+ * Express's `trust proxy` setting, in the three shapes it accepts.
+ *
+ * Checked in this order: a hop count (`'1'` — the recommended form, and the
+ * only one a client cannot forge past), a boolean (`'true'` trusts the entire
+ * `X-Forwarded-For` chain, `'false'` trusts none), or any other non-empty
+ * string, passed to Express verbatim as a subnet/preset list (`'loopback'`,
+ * `'10.0.0.0/8'`). Unset yields `undefined`, leaving Express's default of
+ * ignoring forwarded headers entirely.
+ *
+ * Returns the union structurally rather than importing `TrustProxySetting`
+ * from `@orthacms/bootstrap-server`: this is a leaf helper package, and the
+ * host importing it must not become a dependency of it. The host's own
+ * `trustProxy?: TrustProxySetting` field is what checks the two agree.
+ */
+export declare function readTrustProxy(name?: string): boolean | number | string | undefined;
+/** The deployment modes an Ortha app recognises. */
+export declare const NODE_ENVS: readonly ["development", "test", "production"];
+/** One of {@link NODE_ENVS}. */
+export type NodeEnv = (typeof NODE_ENVS)[number];
+/**
+ * Reads `NODE_ENV`, rejecting a value that is neither recognised nor empty.
+ *
+ * `NODE_ENV !== 'production'` is the switch behind **two** protections at once
+ * — whether the API reference and GraphiQL are published, and whether the
+ * session cookie carries `Secure` — so any value that is not exactly
+ * `production` turns both off. Unset is a legitimate, and the common, local
+ * state; a *typo* is not, and it is indistinguishable from correct
+ * configuration until you read a `Set-Cookie` header. Measured: `produciton`
+ * serves `/reference/json` to an unauthenticated caller and drops `Secure`
+ * from the session cookie, exactly as if nothing had been set (ORT-137).
+ *
+ * Rejecting the typo costs a deployment that spells it right nothing, and
+ * turns a silent downgrade into a refusal to start.
+ */
+export declare function readNodeEnv(): NodeEnv | undefined;
+/**
+ * True only in a deployment that said `production`, with the spelling checked
+ * by {@link readNodeEnv}.
+ */
+export declare function isProduction(): boolean;
+/**
+ * As {@link readList}, but `undefined` when the variable is unset, so the
+ * consumer's own default list survives rather than being replaced by an empty
+ * one.
+ *
+ * The list counterpart to {@link readOptionalPositiveInt}, and needed for the
+ * same reason: a setting whose owner ships a default cannot be handed an empty
+ * array meaning "the deployment said nothing".
+ */
+export declare function readOptionalList(name: string): string[] | undefined;
+/**
+ * A boolean setting: what the deployment said, or `fallback` when it said
+ * nothing.
+ *
+ * Anything other than `true` reads as false, so a typo turns a switch **off**
+ * rather than on. That direction is deliberate: the switches this reads are
+ * kill switches for surfaces that send content to a third party or open a door
+ * for an external agent, and a misspelling should not open one.
+ */
+export declare function readFlag(name: string, fallback: boolean): boolean;
+/**
+ * The value when the setting was configured, `undefined` when it was not.
+ *
+ * The counterpart to {@link defined}: together they replace
+ * `...(x ? { key: … } : {})` at a config site. `build` is a thunk so its body —
+ * often several further reads — runs only when it applies, which is what lets a
+ * whole provider block sit behind one credential check.
+ */
+export declare function when<T>(configured: unknown, build: () => T): T | undefined;
+/**
+ * The same object with every `undefined`-valued key removed.
+ *
+ * A plugin merges its own defaults as `{ ...DEFAULTS, ...config }`, so an
+ * explicit `{ maxSteps: undefined }` does not leave `DEFAULT_RUN_LIMITS.maxSteps`
+ * in place — it erases it. Dropping the key is what "the deployment did not set
+ * this" has to mean, and saying it once at the end of a builder is why a config
+ * file no longer needs a conditional per optional setting.
+ */
+export declare function defined<T extends object>(value: T): T;
+//# sourceMappingURL=env.d.ts.map

package/dist/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAS9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcxE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC1B,IAAI,SAAgB,GACrB,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAavC;AAED,oDAAoD;AACpD,eAAO,MAAM,SAAS,gDAAiD,CAAC;AAExE,gCAAgC;AAChC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,IAAI,OAAO,GAAG,SAAS,CAejD;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAQrD"}

package/dist/lib/env.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * Reading `process.env` into typed configuration.
+ *
+ * A host's `ortha.config.ts` is the one file allowed to touch the environment,
+ * and every deployment writes the same handful of readers to do it: a required
+ * string, a bounded number, a comma list, `TRUST_PROXY`, `NODE_ENV`. They were
+ * duplicated between this repo's host and the scaffolder's template, where the
+ * copies had already drifted — the template's number reader had no
+ * "optional, no default" form, so a generated app could not express a ceiling
+ * that means "leave the plugin's own default alone".
+ *
+ * Every reader here **throws rather than guesses**. That is the whole point of
+ * the module: the failure mode of environment parsing is silence, and a config
+ * value that is quietly wrong is discovered a session TTL later, or by reading
+ * a `Set-Cookie` header, rather than at boot with the variable named.
+ *
+ * The last two exports — {@link when} and {@link defined} — read nothing. They
+ * are here because they are what a host does with the readers' `undefined`:
+ * plugins merge their settings as `{ ...DEFAULTS, ...config }`, so an unset
+ * value must become an *absent key* rather than an explicit `undefined`, which
+ * would erase the default it was meant to leave alone. Every host writing that
+ * as `...(x ? { key } : {})` at each call site is the duplication this module
+ * exists to end.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_ENVS = void 0;
+exports.readEnv = readEnv;
+exports.requireEnv = requireEnv;
+exports.readPositiveInt = readPositiveInt;
+exports.readOptionalPositiveInt = readOptionalPositiveInt;
+exports.readList = readList;
+exports.readTrustProxy = readTrustProxy;
+exports.readNodeEnv = readNodeEnv;
+exports.isProduction = isProduction;
+exports.readOptionalList = readOptionalList;
+exports.readFlag = readFlag;
+exports.when = when;
+exports.defined = defined;
+/**
+ * A trimmed environment value, `undefined` when unset **or empty**.
+ *
+ * The one reader every other reader here is built on, so "empty means not
+ * configured" is decided once. That equivalence matters: `.env.example` ships
+ * keys with no value, and `ANTHROPIC_API_KEY=` has to leave a deployment with
+ * *no* Claude backend rather than one registered with an empty key — a backend
+ * that is in the picker and fails on the first message.
+ */
+function readEnv(name) {
+    return process.env[name]?.trim() || undefined;
+}
+/**
+ * Reads a value the app cannot run without, failing at load rather than
+ * several seconds into boot.
+ *
+ * Left to default to `''`, a missing `DATABASE_URL` reaches `pg` as "use the
+ * libpq defaults", and the first thing that touches the database fails with
+ * whatever the local libpq environment happens to produce (measured: `SASL:
+ * SCRAM-SERVER-FIRST-MESSAGE: client password must be a string`). The server
+ * does fail closed, which is the important half, but nothing in that message
+ * names the variable that was never set.
+ *
+ * @param name The environment variable to read.
+ * @param hint Appended to the error, for a deployment-specific instruction —
+ *   which file to copy, which secret store to look in. Omitted, the message
+ *   says only that there is no usable default.
+ */
+function requireEnv(name, hint) {
+    const raw = readEnv(name);
+    if (!raw) {
+        throw new Error(`Missing required environment variable ${name}. ` +
+            (hint ?? 'The server has no usable default for this value.'));
+    }
+    return raw;
+}
+/**
+ * Reads a numeric setting: the default when unset or empty, the value when it
+ * is a plain positive decimal integer, and an error otherwise.
+ *
+ * This replaces `Number(process.env[x]) || default`, which was wrong in three
+ * directions at once and silent in all of them. `0` is falsy, so it became the
+ * default — `LOGIN_RATE_LIMIT=0` ("block every login") quietly meant 10. A
+ * negative is truthy, so it was accepted — `SESSION_TTL_SECONDS=-1` issued
+ * every session already expired, login answering `201` and the very next
+ * request `401`. And exponent notation parsed, so `GRAPHQL_MAX_DEPTH=1e9`
+ * removed the cost budget that ADR-0008 calls GraphQL's replacement for REST's
+ * structural bound. Refusing to boot names the variable; the alternative was a
+ * deployment that looked configured and was not.
+ *
+ * Empty is deliberately *not* an error: `.env.example` ships several keys with
+ * no value, and a fresh clone must boot from it unchanged.
+ */
+function readPositiveInt(name, fallback) {
+    return readOptionalPositiveInt(name) ?? fallback;
+}
+/**
+ * As {@link readPositiveInt}, but `undefined` when unset — no default to fall
+ * back to.
+ *
+ * The form a *ceiling* needs. A plugin that ships its own default cannot be
+ * handed `{ maxSteps: undefined }`, because spreading that overwrites the
+ * default with nothing; the caller conditionally spreads on this instead.
+ */
+function readOptionalPositiveInt(name) {
+    const raw = readEnv(name);
+    if (!raw) {
+        return undefined;
+    }
+    // Plain decimal digits only. `Number` would also take `1e9`, `0x20` and
+    // `Infinity`, none of which anyone means to write in a `.env`.
+    if (!/^\d+$/.test(raw) || Number(raw) <= 0) {
+        throw new Error(`Environment variable ${name} must be a positive whole number ` +
+            `(got "${raw}").`);
+    }
+    return Number(raw);
+}
+/**
+ * A comma-separated list setting, trimmed and emptied of blanks.
+ *
+ * An explicitly empty value yields an empty list rather than the fallback,
+ * because "allow no origins" is a setting somebody means.
+ */
+function readList(name, fallback) {
+    return (process.env[name] ?? fallback)
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+/**
+ * Express's `trust proxy` setting, in the three shapes it accepts.
+ *
+ * Checked in this order: a hop count (`'1'` — the recommended form, and the
+ * only one a client cannot forge past), a boolean (`'true'` trusts the entire
+ * `X-Forwarded-For` chain, `'false'` trusts none), or any other non-empty
+ * string, passed to Express verbatim as a subnet/preset list (`'loopback'`,
+ * `'10.0.0.0/8'`). Unset yields `undefined`, leaving Express's default of
+ * ignoring forwarded headers entirely.
+ *
+ * Returns the union structurally rather than importing `TrustProxySetting`
+ * from `@orthacms/bootstrap-server`: this is a leaf helper package, and the
+ * host importing it must not become a dependency of it. The host's own
+ * `trustProxy?: TrustProxySetting` field is what checks the two agree.
+ */
+function readTrustProxy(name = 'TRUST_PROXY') {
+    const raw = readEnv(name);
+    if (!raw) {
+        return undefined;
+    }
+    const hops = Number(raw);
+    if (Number.isInteger(hops) && hops >= 0) {
+        return hops;
+    }
+    if (raw === 'true' || raw === 'false') {
+        return raw === 'true';
+    }
+    return raw;
+}
+/** The deployment modes an Ortha app recognises. */
+exports.NODE_ENVS = ['development', 'test', 'production'];
+/**
+ * Reads `NODE_ENV`, rejecting a value that is neither recognised nor empty.
+ *
+ * `NODE_ENV !== 'production'` is the switch behind **two** protections at once
+ * — whether the API reference and GraphiQL are published, and whether the
+ * session cookie carries `Secure` — so any value that is not exactly
+ * `production` turns both off. Unset is a legitimate, and the common, local
+ * state; a *typo* is not, and it is indistinguishable from correct
+ * configuration until you read a `Set-Cookie` header. Measured: `produciton`
+ * serves `/reference/json` to an unauthenticated caller and drops `Secure`
+ * from the session cookie, exactly as if nothing had been set (ORT-137).
+ *
+ * Rejecting the typo costs a deployment that spells it right nothing, and
+ * turns a silent downgrade into a refusal to start.
+ */
+function readNodeEnv() {
+    const raw = readEnv('NODE_ENV');
+    if (!raw) {
+        return undefined;
+    }
+    if (!exports.NODE_ENVS.includes(raw)) {
+        throw new Error(`NODE_ENV is "${raw}", which this app does not recognise — expected ` +
+            `one of ${exports.NODE_ENVS.join(', ')}, or nothing at all for local ` +
+            'development. Anything else reads as "not production", which ' +
+            'publishes the API reference and drops `Secure` from the session ' +
+            'cookie.');
+    }
+    return raw;
+}
+/**
+ * True only in a deployment that said `production`, with the spelling checked
+ * by {@link readNodeEnv}.
+ */
+function isProduction() {
+    return readNodeEnv() === 'production';
+}
+/**
+ * As {@link readList}, but `undefined` when the variable is unset, so the
+ * consumer's own default list survives rather than being replaced by an empty
+ * one.
+ *
+ * The list counterpart to {@link readOptionalPositiveInt}, and needed for the
+ * same reason: a setting whose owner ships a default cannot be handed an empty
+ * array meaning "the deployment said nothing".
+ */
+function readOptionalList(name) {
+    return when(readEnv(name), () => readList(name, ''));
+}
+/**
+ * A boolean setting: what the deployment said, or `fallback` when it said
+ * nothing.
+ *
+ * Anything other than `true` reads as false, so a typo turns a switch **off**
+ * rather than on. That direction is deliberate: the switches this reads are
+ * kill switches for surfaces that send content to a third party or open a door
+ * for an external agent, and a misspelling should not open one.
+ */
+function readFlag(name, fallback) {
+    const raw = readEnv(name);
+    return raw === undefined ? fallback : raw === 'true';
+}
+/**
+ * The value when the setting was configured, `undefined` when it was not.
+ *
+ * The counterpart to {@link defined}: together they replace
+ * `...(x ? { key: … } : {})` at a config site. `build` is a thunk so its body —
+ * often several further reads — runs only when it applies, which is what lets a
+ * whole provider block sit behind one credential check.
+ */
+function when(configured, build) {
+    return configured ? build() : undefined;
+}
+/**
+ * The same object with every `undefined`-valued key removed.
+ *
+ * A plugin merges its own defaults as `{ ...DEFAULTS, ...config }`, so an
+ * explicit `{ maxSteps: undefined }` does not leave `DEFAULT_RUN_LIMITS.maxSteps`
+ * in place — it erases it. Dropping the key is what "the deployment did not set
+ * this" has to mean, and saying it once at the end of a builder is why a config
+ * file no longer needs a conditional per optional setting.
+ */
+function defined(value) {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined) {
+            result[key] = item;
+        }
+    }
+    return result;
+}

package/dist/lib/filters/operator-support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator-support.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/operator-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAsD1D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAClC,eAAe,EACf,SAAS,cAAc,EAAE,CAQ5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CACxB,IAAI,EAAE,eAAe,GACtB,SAAS,cAAc,EAAE,GAAG,SAAS,CAIvC"}
+{"version":3,"file":"operator-support.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/operator-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAmE1D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAClC,eAAe,EACf,SAAS,cAAc,EAAE,CAQ5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CACxB,IAAI,EAAE,eAAe,GACtB,SAAS,cAAc,EAAE,GAAG,SAAS,CAIvC"}

package/dist/lib/filters/operator-support.js

@@ -47,6 +47,18 @@ const COMPARABLE_OPERATORS = [
     types_1.FilterOperator.Nin,
     types_1.FilterOperator.Null
 ];
+/**
+ * {@link COMPARABLE_OPERATORS} plus the relative window.
+ *
+ * `within_last` is date-only because it compares against `now()` — asking for
+ * "titles within the last 7 days" is not a narrower query, it is a category
+ * error, and Postgres would report it as a type mismatch rather than as
+ * something the client can fix.
+ */
+const DATE_OPERATORS = [
+    ...COMPARABLE_OPERATORS,
+    types_1.FilterOperator.WithinLast
+];
 /** {@link COMPARABLE_OPERATORS} plus the text-only `~~` family. */
 const TEXT_OPERATORS = [
     ...COMPARABLE_OPERATORS,
@@ -67,7 +79,7 @@ exports.OPERATORS_BY_TYPE = {
     [types_1.ScalarFieldType.Number]: COMPARABLE_OPERATORS,
     [types_1.ScalarFieldType.Boolean]: COMPARABLE_OPERATORS,
     [types_1.ScalarFieldType.Uuid]: COMPARABLE_OPERATORS,
-    [types_1.ScalarFieldType.Date]: COMPARABLE_OPERATORS
+    [types_1.ScalarFieldType.Date]: DATE_OPERATORS
 };
 /**
  * The operators `type` accepts, or `undefined` when the type is not one this

package/dist/lib/filters/resolve-leaf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-leaf.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/resolve-leaf.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAqB,MAAM,SAAS,CAAC;AAQ7E;;;;GAIG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACxB,YAAY,CAkEd"}
+{"version":3,"file":"resolve-leaf.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/resolve-leaf.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACR,YAAY,EACZ,YAAY,EAGf,MAAM,SAAS,CAAC;AAQjB;;;;GAIG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACxB,YAAY,CAkEd"}

package/dist/lib/filters/resolve-leaf.js

@@ -71,6 +71,9 @@ function assertOperatorAllowed(field, op, path) {
 }
 function coerce(raw, field, op, path, maxInListLength) {
     const pathStr = path.join('.');
+    if (op === types_1.FilterOperator.WithinLast) {
+        return withinLastValue(raw, pathStr);
+    }
     if (op === types_1.FilterOperator.Null) {
         if (raw === 'true' || raw === true)
             return true;
@@ -100,6 +103,34 @@ function coerce(raw, field, op, path, maxInListLength) {
     }
     return scalarOf(raw, field, pathStr);
 }
+/** Units a `within_last` window may name, as a set for membership checks. */
+const WITHIN_LAST_UNITS = new Set(Object.values(types_1.WithinLastUnit));
+/**
+ * Coerce a `within_last` value — `{ n, unit }`, the only object-shaped value in
+ * the grammar.
+ *
+ * The bound on `n` is not decoration. `now() - make_interval(days => 1e9)`
+ * overflows Postgres' timestamp range and raises a `22008` the caller sees as a
+ * 500; a client asking for a window that long means to say "all of it", and
+ * should be told so with a 400 rather than a stack trace. Ten years of minutes
+ * is far past any real window and comfortably inside what a timestamp can hold.
+ */
+const MAX_WITHIN_LAST_N = 10_000_000;
+function withinLastValue(raw, pathStr) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, 'within_last expects { n, unit }', { path: pathStr, op: types_1.FilterOperator.WithinLast });
+    }
+    const value = raw;
+    const n = Number(value['n']);
+    const unit = value['unit'];
+    if (!Number.isInteger(n) || n < 1 || n > MAX_WITHIN_LAST_N) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `within_last n must be an integer between 1 and ${MAX_WITHIN_LAST_N}`, { path: pathStr, op: types_1.FilterOperator.WithinLast, value: value['n'] });
+    }
+    if (typeof unit !== 'string' || !WITHIN_LAST_UNITS.has(unit)) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `within_last unit must be one of ${[...WITHIN_LAST_UNITS].join(', ')}`, { path: pathStr, op: types_1.FilterOperator.WithinLast, value: unit });
+    }
+    return { n, unit: unit };
+}
 function scalarOf(v, field, pathStr) {
     // A filter value has to be a scalar. `String(v)` on anything else produces
     // a plausible-looking string that is then MATCHED AGAINST rather than

package/dist/lib/filters/scalar-op.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scalar-op.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/scalar-op.ts"],"names":[],"mappings":"AAAA,OAAO,EAeH,KAAK,SAAS,EACd,KAAK,GAAG,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAiBzC;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAClB,GAAG,EAAE,SAAS,EACd,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,OAAO,GACf,GAAG,CAqCL"}
+{"version":3,"file":"scalar-op.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/scalar-op.ts"],"names":[],"mappings":"AAAA,OAAO,EAgBH,KAAK,SAAS,EACd,KAAK,GAAG,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAkB,MAAM,SAAS,CAAC;AAkBzD;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAClB,GAAG,EAAE,SAAS,EACd,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,OAAO,GACf,GAAG,CAuCL"}

package/dist/lib/filters/scalar-op.js

@@ -54,6 +54,8 @@ function scalar(col, op, value) {
             return negative(col, (0, drizzle_orm_1.notIlike)(col, String(value)));
         case types_1.FilterOperator.Null:
             return value === true ? (0, drizzle_orm_1.isNull)(col) : (0, drizzle_orm_1.isNotNull)(col);
+        case types_1.FilterOperator.WithinLast:
+            return withinLast(col, value);
         default:
             // The parser validates `op` against the vocabulary, so this is
             // unreachable — but falling out of the switch returned `undefined`,
@@ -64,3 +66,27 @@ function scalar(col, op, value) {
             throw new filter_exceptions_1.FilterSchemaException(`no translation for operator "${String(op)}"`);
     }
 }
+/**
+ * `column >= now() - <n> <unit>`.
+ *
+ * The cutoff is computed by **Postgres, at query time** — which is the whole
+ * point of the operator surviving to the server. A cutoff computed here in
+ * JavaScript would be identical for one request and wrong for a stored filter
+ * replayed a month later.
+ *
+ * A `switch` over the three units rather than interpolating the unit into the
+ * SQL: `make_interval`'s argument names cannot be parameterised, so building
+ * the fragment from a variable would mean `sql.raw` on a value that came off
+ * the wire. The parser already restricts the unit to these three, and this way
+ * there is no path by which that could stop being true.
+ */
+function withinLast(col, window) {
+    switch (window.unit) {
+        case types_1.WithinLastUnit.Minutes:
+            return (0, drizzle_orm_1.gte)(col, (0, drizzle_orm_1.sql) `now() - make_interval(mins => ${window.n})`);
+        case types_1.WithinLastUnit.Hours:
+            return (0, drizzle_orm_1.gte)(col, (0, drizzle_orm_1.sql) `now() - make_interval(hours => ${window.n})`);
+        default:
+            return (0, drizzle_orm_1.gte)(col, (0, drizzle_orm_1.sql) `now() - make_interval(days => ${window.n})`);
+    }
+}

package/dist/lib/filters/types.d.ts

@@ -25,6 +25,20 @@ export declare const FilterOperator: {
     readonly Ilike: "ilike";
     readonly Nilike: "nilike";
     readonly Null: "null";
+    /**
+     * `column >= now() - <n> <unit>` — a window measured from **query time**,
+     * not from the moment the filter was written.
+     *
+     * The distinction is invisible in a URL and decisive in a stored one. The
+     * admin's query builder resolves its own `within_last` into a concrete
+     * `gte` cutoff when it serialises a filter into a link, deliberately: a
+     * shared deep link should keep showing the same rows. A filter that is
+     * *stored and replayed* — an alarm rule — must mean the opposite, or
+     * "not updated in 90 days" silently becomes "not updated since the day the
+     * rule was written". So the operator survives to the server, and the caller
+     * chooses which meaning it wants.
+     */
+    readonly WithinLast: "within_last";
 };
 /** Standard REST operator names. Translator maps each to a Drizzle helper. */
 export type FilterOperator = (typeof FilterOperator)[keyof typeof FilterOperator];
@@ -189,6 +203,21 @@ export interface FilterSchema {
      */
     maxInListLength?: number;
 }
+/** Time units a {@link FilterOperator.WithinLast} window may be measured in. */
+export declare const WithinLastUnit: {
+    readonly Minutes: "minutes";
+    readonly Hours: "hours";
+    readonly Days: "days";
+};
+/** One of the {@link WithinLastUnit} values. */
+export type WithinLastUnit = (typeof WithinLastUnit)[keyof typeof WithinLastUnit];
+/** The coerced value of a `within_last` leaf. */
+export interface WithinLastValue {
+    /** How many units back the window reaches. A positive integer. */
+    n: number;
+    /** The unit `n` is counted in. */
+    unit: WithinLastUnit;
+}
 /** Parser output, one node per URL filter entry. */
 export interface ParsedFilter {
     /** Dotted path split into segments, e.g. `['workspaces','name']`. */

package/dist/lib/filters/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,GAAG,GAAG,SAAS,CAAC;AAEnE,8EAA8E;AAC9E,eAAO,MAAM,cAAc;;;;;;;;;;;;;CAajB,CAAC;AAEX,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GACtB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEzD,+DAA+D;AAC/D,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAEX,oDAAoD;AACpD,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAC9B,+DAA+D;IAC/D,IAAI,EAAE,eAAe,CAAC;IACtB,uCAAuC;IACvC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,oCAAoC;AACpC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,cAAc,GACpB;IACI,iEAAiE;IACjE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC;IACnC,sCAAsC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,0DAA0D;IAC1D,EAAE,EAAE,SAAS,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,GACD;IACI,mCAAmC;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,oBAAoB;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,mEAAmE;IACnE,EAAE,EAAE,SAAS,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gEAAgE;IAChE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,GACD;IACI,gEAAgE;IAChE,IAAI,EAAE,cAAc,CAAC;IACrB,gCAAgC;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,wDAAwD;IACxD,EAAE,EAAE,SAAS,CAAC;IACd,wDAAwD;IACxD,QAAQ,EAAE,SAAS,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,GACD;IACI,uDAAuD;IACvD,IAAI,EAAE,kBAAkB,CAAC;IACzB,yCAAyC;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,4DAA4D;IAC5D,EAAE,EAAE,SAAS,CAAC;IACd;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,CAAC;AAER,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IACzB,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IACzB,qEAAqE;IACrE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0BAA0B;IAC1B,EAAE,EAAE,cAAc,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC5C,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,UAAU,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/filters/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = void 0;
+exports.WithinLastUnit = exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = void 0;
 /** Named constants for `FilterOperator` — use in switches and comparisons. */
 exports.FilterOperator = {
     Eq: 'eq',
@@ -14,7 +14,21 @@ exports.FilterOperator = {
     Like: 'like',
     Ilike: 'ilike',
     Nilike: 'nilike',
-    Null: 'null'
+    Null: 'null',
+    /**
+     * `column >= now() - <n> <unit>` — a window measured from **query time**,
+     * not from the moment the filter was written.
+     *
+     * The distinction is invisible in a URL and decisive in a stored one. The
+     * admin's query builder resolves its own `within_last` into a concrete
+     * `gte` cutoff when it serialises a filter into a link, deliberately: a
+     * shared deep link should keep showing the same rows. A filter that is
+     * *stored and replayed* — an alarm rule — must mean the opposite, or
+     * "not updated in 90 days" silently becomes "not updated since the day the
+     * rule was written". So the operator survives to the server, and the caller
+     * chooses which meaning it wants.
+     */
+    WithinLast: 'within_last'
 };
 /** Named constants for `ScalarFieldType` — use in switches. */
 exports.ScalarFieldType = {
@@ -33,3 +47,9 @@ exports.RelationKind = {
     ManyToMany: 'many-to-many',
     SelfReferential: 'self-referential'
 };
+/** Time units a {@link FilterOperator.WithinLast} window may be measured in. */
+exports.WithinLastUnit = {
+    Minutes: 'minutes',
+    Hours: 'hours',
+    Days: 'days'
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@orthacms/utils-server",
-    "version": "0.4.2",
+    "version": "0.4.3",
     "description": "@orthacms/utils-server — part of Ortha CMS.",
     "license": "MIT",
     "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/utils/server",