@spotto/semantic-query 1.0.70-alpha.27 → 1.0.70-alpha.29

package/dist/dates.d.ts

@@ -1,32 +1,32 @@
-import { SemanticDateValue } from '@spotto/contract';
-/**
- * The semantic-query date engine.
- *
- * A saved query keeps relative dates SYMBOLIC — "last 30 days" means the last
- * 30 days forever, not the 30 days before it was saved — so every execution
- * resolves them afresh. This module is the one place that resolution happens,
- * for every consumer: the client evaluating against its local cache and the
- * server compiling to Mongo resolve the same words to the same instant.
- *
- * Everything takes an EXPLICIT `now`. Nothing here reads the clock. That is
- * what makes a resolved query reproducible: the same query, catalogue, `now`
- * and timezone always produce the same boundaries, whoever resolved them.
- */
-/** A calendar date with no timezone attached. */
-export interface SemanticCivilDate {
-    y: number;
-    m: number;
-    d: number;
-}
-/** Resolve either semantic date form (ISO string or relative object) to a civil date. */
-export declare function resolveSemanticDate(v: SemanticDateValue, now: Date, tz: string): SemanticCivilDate;
-/** DATE custom fields store day-number integers: 15 Aug 2026 → 20260815. */
-export declare function semanticCivilToYyyymmdd(c: SemanticCivilDate): number;
-/**
- * Epoch-ms boundary for comparing against a millisecond timestamp field.
- *
- * `gt`/`lte` sit at the END of the named day (so "lte 2026-07-27" includes all
- * of the 27th); `gte`/`lt` at its START. Without this, half of every inclusive
- * range query silently drops a day.
- */
-export declare function semanticDateBoundaryMs(v: SemanticDateValue, operator: 'gt' | 'gte' | 'lt' | 'lte', now: Date, tz: string): number;
+import { SemanticDateValue } from '@spotto/contract';
+/**
+ * The semantic-query date engine.
+ *
+ * A saved query keeps relative dates SYMBOLIC — "last 30 days" means the last
+ * 30 days forever, not the 30 days before it was saved — so every execution
+ * resolves them afresh. This module is the one place that resolution happens,
+ * for every consumer: the client evaluating against its local cache and the
+ * server compiling to Mongo resolve the same words to the same instant.
+ *
+ * Everything takes an EXPLICIT `now`. Nothing here reads the clock. That is
+ * what makes a resolved query reproducible: the same query, catalogue, `now`
+ * and timezone always produce the same boundaries, whoever resolved them.
+ */
+/** A calendar date with no timezone attached. */
+export interface SemanticCivilDate {
+    y: number;
+    m: number;
+    d: number;
+}
+/** Resolve either semantic date form (ISO string or relative object) to a civil date. */
+export declare function resolveSemanticDate(v: SemanticDateValue, now: Date, tz: string): SemanticCivilDate;
+/** DATE custom fields store day-number integers: 15 Aug 2026 → 20260815. */
+export declare function semanticCivilToYyyymmdd(c: SemanticCivilDate): number;
+/**
+ * Epoch-ms boundary for comparing against a millisecond timestamp field.
+ *
+ * `gt`/`lte` sit at the END of the named day (so "lte 2026-07-27" includes all
+ * of the 27th); `gte`/`lt` at its START. Without this, half of every inclusive
+ * range query silently drops a day.
+ */
+export declare function semanticDateBoundaryMs(v: SemanticDateValue, operator: 'gt' | 'gte' | 'lt' | 'lte', now: Date, tz: string): number;

package/dist/dates.js

@@ -1,105 +1,105 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.semanticDateBoundaryMs = exports.semanticCivilToYyyymmdd = exports.resolveSemanticDate = void 0;
-const dayjs_1 = __importDefault(require("dayjs"));
-const utc_1 = __importDefault(require("dayjs/plugin/utc"));
-const timezone_1 = __importDefault(require("dayjs/plugin/timezone"));
-const isoWeek_1 = __importDefault(require("dayjs/plugin/isoWeek"));
-const quarterOfYear_1 = __importDefault(require("dayjs/plugin/quarterOfYear"));
-dayjs_1.default.extend(utc_1.default);
-dayjs_1.default.extend(timezone_1.default);
-dayjs_1.default.extend(isoWeek_1.default);
-dayjs_1.default.extend(quarterOfYear_1.default);
-const SEMANTIC_ISO_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
-function civilOf(d) {
-    return { y: d.year(), m: d.month() + 1, d: d.date() };
-}
-/** Resolve a structured semantic relative date to a civil date in `tz`. */
-function resolveSemanticRelativeDate(v, now, tz) {
-    const today = (0, dayjs_1.default)(now).tz(tz);
-    const { base, offset, position } = v;
-    switch (base) {
-        case 'day':
-            return civilOf(today.add(offset, 'day'));
-        case 'week': {
-            // 'same' keeps the weekday — "a week from today" is +7 days, not the
-            // following Monday. `start`/`end` snap to the ISO week's boundaries
-            // (Monday start, matching the platform's UNIT_MAP choice).
-            if (position === 'same')
-                return civilOf(today.add(offset, 'week'));
-            const monday = today.add(offset, 'week').startOf('isoWeek');
-            return civilOf(position === 'end' ? monday.add(6, 'day') : monday);
-        }
-        case 'month': {
-            // 'same' keeps the day-of-month; dayjs clamps short months
-            // (31 Jan + 1 month = 28/29 Feb), which is the specified behaviour.
-            if (position === 'same')
-                return civilOf(today.add(offset, 'month'));
-            const t = today.add(offset, 'month');
-            return civilOf(position === 'end' ? t.endOf('month') : t.startOf('month'));
-        }
-        case 'quarter': {
-            if (position === 'same')
-                return civilOf(today.add(offset * 3, 'month'));
-            const t = today.add(offset, 'quarter');
-            return civilOf(position === 'end'
-                ? t.endOf('quarter')
-                : t.startOf('quarter'));
-        }
-        case 'year': {
-            if (position === 'same')
-                return civilOf(today.add(offset * 12, 'month'));
-            const t = today.add(offset, 'year');
-            return civilOf(position === 'end' ? t.endOf('year') : t.startOf('year'));
-        }
-    }
-    throw new Error(`unknown relative base '${String(base)}'`);
-}
-/** Resolve either semantic date form (ISO string or relative object) to a civil date. */
-function resolveSemanticDate(v, now, tz) {
-    if (typeof v === 'string') {
-        const m = SEMANTIC_ISO_RE.exec(v.trim());
-        if (!m)
-            throw new Error(`date must be ISO YYYY-MM-DD, got '${v}'`);
-        const civil = { y: Number(m[1]), m: Number(m[2]), d: Number(m[3]) };
-        // The pattern alone accepts 2026-02-31 and 2026-13-01, which resolve to an
-        // Invalid Date and then to a NaN boundary — a query that runs and matches
-        // nothing. Reject the impossible date instead. (Checked arithmetically:
-        // dayjs' strict parsing needs the customParseFormat plugin, which this
-        // module deliberately does not load.)
-        const daysInMonth = new Date(Date.UTC(civil.y, civil.m, 0)).getUTCDate();
-        if (civil.m < 1 || civil.m > 12 || civil.d < 1 || civil.d > daysInMonth) {
-            throw new Error(`'${v}' is not a real calendar date`);
-        }
-        return civil;
-    }
-    if (v && typeof v === 'object' && v.relative) {
-        return resolveSemanticRelativeDate(v, now, tz);
-    }
-    throw new Error(`unrecognised date value: ${JSON.stringify(v)}`);
-}
-exports.resolveSemanticDate = resolveSemanticDate;
-/** DATE custom fields store day-number integers: 15 Aug 2026 → 20260815. */
-function semanticCivilToYyyymmdd(c) {
-    return c.y * 10000 + c.m * 100 + c.d;
-}
-exports.semanticCivilToYyyymmdd = semanticCivilToYyyymmdd;
-/**
- * Epoch-ms boundary for comparing against a millisecond timestamp field.
- *
- * `gt`/`lte` sit at the END of the named day (so "lte 2026-07-27" includes all
- * of the 27th); `gte`/`lt` at its START. Without this, half of every inclusive
- * range query silently drops a day.
- */
-function semanticDateBoundaryMs(v, operator, now, tz) {
-    const c = resolveSemanticDate(v, now, tz);
-    const iso = `${String(c.y).padStart(4, '0')}-${String(c.m).padStart(2, '0')}-${String(c.d).padStart(2, '0')}`;
-    const day = dayjs_1.default.tz(iso, tz);
-    const endOfDay = operator === 'gt' || operator === 'lte';
-    return (endOfDay ? day.endOf('day') : day.startOf('day')).valueOf();
-}
-exports.semanticDateBoundaryMs = semanticDateBoundaryMs;
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semanticDateBoundaryMs = exports.semanticCivilToYyyymmdd = exports.resolveSemanticDate = void 0;
+const dayjs_1 = __importDefault(require("dayjs"));
+const utc_1 = __importDefault(require("dayjs/plugin/utc"));
+const timezone_1 = __importDefault(require("dayjs/plugin/timezone"));
+const isoWeek_1 = __importDefault(require("dayjs/plugin/isoWeek"));
+const quarterOfYear_1 = __importDefault(require("dayjs/plugin/quarterOfYear"));
+dayjs_1.default.extend(utc_1.default);
+dayjs_1.default.extend(timezone_1.default);
+dayjs_1.default.extend(isoWeek_1.default);
+dayjs_1.default.extend(quarterOfYear_1.default);
+const SEMANTIC_ISO_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function civilOf(d) {
+    return { y: d.year(), m: d.month() + 1, d: d.date() };
+}
+/** Resolve a structured semantic relative date to a civil date in `tz`. */
+function resolveSemanticRelativeDate(v, now, tz) {
+    const today = (0, dayjs_1.default)(now).tz(tz);
+    const { base, offset, position } = v;
+    switch (base) {
+        case 'day':
+            return civilOf(today.add(offset, 'day'));
+        case 'week': {
+            // 'same' keeps the weekday — "a week from today" is +7 days, not the
+            // following Monday. `start`/`end` snap to the ISO week's boundaries
+            // (Monday start, matching the platform's UNIT_MAP choice).
+            if (position === 'same')
+                return civilOf(today.add(offset, 'week'));
+            const monday = today.add(offset, 'week').startOf('isoWeek');
+            return civilOf(position === 'end' ? monday.add(6, 'day') : monday);
+        }
+        case 'month': {
+            // 'same' keeps the day-of-month; dayjs clamps short months
+            // (31 Jan + 1 month = 28/29 Feb), which is the specified behaviour.
+            if (position === 'same')
+                return civilOf(today.add(offset, 'month'));
+            const t = today.add(offset, 'month');
+            return civilOf(position === 'end' ? t.endOf('month') : t.startOf('month'));
+        }
+        case 'quarter': {
+            if (position === 'same')
+                return civilOf(today.add(offset * 3, 'month'));
+            const t = today.add(offset, 'quarter');
+            return civilOf(position === 'end'
+                ? t.endOf('quarter')
+                : t.startOf('quarter'));
+        }
+        case 'year': {
+            if (position === 'same')
+                return civilOf(today.add(offset * 12, 'month'));
+            const t = today.add(offset, 'year');
+            return civilOf(position === 'end' ? t.endOf('year') : t.startOf('year'));
+        }
+    }
+    throw new Error(`unknown relative base '${String(base)}'`);
+}
+/** Resolve either semantic date form (ISO string or relative object) to a civil date. */
+function resolveSemanticDate(v, now, tz) {
+    if (typeof v === 'string') {
+        const m = SEMANTIC_ISO_RE.exec(v.trim());
+        if (!m)
+            throw new Error(`date must be ISO YYYY-MM-DD, got '${v}'`);
+        const civil = { y: Number(m[1]), m: Number(m[2]), d: Number(m[3]) };
+        // The pattern alone accepts 2026-02-31 and 2026-13-01, which resolve to an
+        // Invalid Date and then to a NaN boundary — a query that runs and matches
+        // nothing. Reject the impossible date instead. (Checked arithmetically:
+        // dayjs' strict parsing needs the customParseFormat plugin, which this
+        // module deliberately does not load.)
+        const daysInMonth = new Date(Date.UTC(civil.y, civil.m, 0)).getUTCDate();
+        if (civil.m < 1 || civil.m > 12 || civil.d < 1 || civil.d > daysInMonth) {
+            throw new Error(`'${v}' is not a real calendar date`);
+        }
+        return civil;
+    }
+    if (v && typeof v === 'object' && v.relative) {
+        return resolveSemanticRelativeDate(v, now, tz);
+    }
+    throw new Error(`unrecognised date value: ${JSON.stringify(v)}`);
+}
+exports.resolveSemanticDate = resolveSemanticDate;
+/** DATE custom fields store day-number integers: 15 Aug 2026 → 20260815. */
+function semanticCivilToYyyymmdd(c) {
+    return c.y * 10000 + c.m * 100 + c.d;
+}
+exports.semanticCivilToYyyymmdd = semanticCivilToYyyymmdd;
+/**
+ * Epoch-ms boundary for comparing against a millisecond timestamp field.
+ *
+ * `gt`/`lte` sit at the END of the named day (so "lte 2026-07-27" includes all
+ * of the 27th); `gte`/`lt` at its START. Without this, half of every inclusive
+ * range query silently drops a day.
+ */
+function semanticDateBoundaryMs(v, operator, now, tz) {
+    const c = resolveSemanticDate(v, now, tz);
+    const iso = `${String(c.y).padStart(4, '0')}-${String(c.m).padStart(2, '0')}-${String(c.d).padStart(2, '0')}`;
+    const day = dayjs_1.default.tz(iso, tz);
+    const endOfDay = operator === 'gt' || operator === 'lte';
+    return (endOfDay ? day.endOf('day') : day.startOf('day')).valueOf();
+}
+exports.semanticDateBoundaryMs = semanticDateBoundaryMs;
 //# sourceMappingURL=dates.js.map

package/dist/evaluate.d.ts

@@ -1,28 +1,28 @@
-import { SemanticQuery } from '@spotto/contract';
-import { SemanticAccountSchema, SemanticCompileOptions } from './types';
-/**
- * Reference semantics for the semantic-query language, evaluated directly over
- * asset documents in memory.
- *
- * This is deliberately an INDEPENDENT implementation of what each condition
- * MEANS — not a second call into the compiler. It exists to be the oracle in
- * the acceptance property:
- *
- *     evaluate(query, docs)  ===  find(compile(query))  restricted to docs
- *
- * If the two disagree, one of them is wrong, and the disagreement is the bug
- * report. This is what catches the silent-wrong-rows class — encoding
- * mistakes that otherwise surface as a plausibly-sized result set.
- *
- * Scope note: like the compiler, this evaluates CONDITIONS ONLY. Org and
- * user-group scoping belong to the pipeline scaffold; the oracle harness
- * restricts its corpus accordingly before comparing.
- *
- * Two deliberate mirrors of compiler decisions:
- * - Custom fields match at EITHER level (asset `fieldValues` or the type's
- *   `typeFieldValuesAll`, joined by `typeId`) with no override precedence —
- *   the platform's shipped flat-filter semantic.
- */
-declare type Doc = Record<string, any>;
-export declare function evaluateSemanticQuery(query: SemanticQuery, docs: Doc[], schema: SemanticAccountSchema, opts?: SemanticCompileOptions): Doc[];
-export {};
+import { SemanticQuery } from '@spotto/contract';
+import { SemanticAccountSchema, SemanticCompileOptions } from './types';
+/**
+ * Reference semantics for the semantic-query language, evaluated directly over
+ * asset documents in memory.
+ *
+ * This is deliberately an INDEPENDENT implementation of what each condition
+ * MEANS — not a second call into the compiler. It exists to be the oracle in
+ * the acceptance property:
+ *
+ *     evaluate(query, docs)  ===  find(compile(query))  restricted to docs
+ *
+ * If the two disagree, one of them is wrong, and the disagreement is the bug
+ * report. This is what catches the silent-wrong-rows class — encoding
+ * mistakes that otherwise surface as a plausibly-sized result set.
+ *
+ * Scope note: like the compiler, this evaluates CONDITIONS ONLY. Org and
+ * user-group scoping belong to the pipeline scaffold; the oracle harness
+ * restricts its corpus accordingly before comparing.
+ *
+ * Two deliberate mirrors of compiler decisions:
+ * - Custom fields match at EITHER level (asset `fieldValues` or the type's
+ *   `typeFieldValuesAll`, joined by `typeId`) with no override precedence —
+ *   the platform's shipped flat-filter semantic.
+ */
+declare type Doc = Record<string, any>;
+export declare function evaluateSemanticQuery(query: SemanticQuery, docs: Doc[], schema: SemanticAccountSchema, opts?: SemanticCompileOptions): Doc[];
+export {};