@omgbase/oqx 0.10.2 → 0.12.0

package/src/semantics.ts

@@ -10,12 +10,20 @@
 //   • Absence: `undefined` and `null` are the same absent value.
 //   • Equality (== / !=): typed and strict — no cross-type coercion, so
 //     `5 == "5"` is false. Two absent values are equal.
-//   • Ordering (< <= > >=): a comparison with an absent operand is false (never
-//     throws, never orders). Numbers and strings order naturally; mixed types do
-//     not order (false).
-//   • Truthiness: JavaScript truthiness of the value.
-//   • `in`: membership in an array (by ==), substring in a string, key in an
+//   • Ordering (< <= > >=): only number/number and string/string order — numbers
+//     numerically, strings by Unicode code point. Every other pairing (an absent
+//     operand, mixed types, booleans, containers) is false; nothing throws.
+//   • Arithmetic: an absent operand makes the result absent (`+` included, even
+//     when the other side is a string). `+` with a string side concatenates the
+//     operands' string forms.
+//   • Truthiness: absent, false, 0, -0, and "" are falsy; everything else truthy.
+//   • `in`: membership in an array (by ==), substring in a string, OWN key of an
 //     object, or coverage by a range (lo..hi / lo...hi / open-ended).
+//   • Identity / structural keys: `canonicalKey` — a type-tagged serialization,
+//     so `1` and `"1"` differ and object key order is ignored. Never `String()`.
+
+import { compileRegex } from "./regex.ts";
+import type { RegexDialect } from "./regex.ts";
 
 /** Equality with absence-normalization (undefined ≡ null) and strict typing. */
 export function equals(a: unknown, b: unknown): boolean {
@@ -24,23 +32,58 @@ export function equals(a: unknown, b: unknown): boolean {
   return x === y;
 }
 
-/** The six relational operators. Absent operands (for ordering ops) yield false. */
+/** Compare two strings by Unicode code point (not UTF-16 code unit): -1, 0, 1. */
+export function compareStrings(a: string, b: string): number {
+  if (a === b) return 0;
+  let i = 0, j = 0;
+  while (i < a.length && j < b.length) {
+    const ca = a.codePointAt(i)!, cb = b.codePointAt(j)!;
+    if (ca !== cb) return ca < cb ? -1 : 1;
+    i += ca > 0xffff ? 2 : 1;
+    j += cb > 0xffff ? 2 : 1;
+  }
+  return i < a.length ? 1 : j < b.length ? -1 : 0;
+}
+
+/** The ordering of two values, or `undefined` when they do not order: only two
+ * numbers (numerically) or two strings (by code point) order. Absent operands,
+ * mixed types, booleans, arrays, and objects never order. */
+export function compare(a: unknown, b: unknown): number | undefined {
+  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
+  if (typeof a === "string" && typeof b === "string") return compareStrings(a, b);
+  return undefined;
+}
+
+/** The six relational operators. Pairs that do not order (see `compare`) yield false. */
 export function relate(op: string, a: unknown, b: unknown): boolean {
   if (op === "==") return equals(a, b);
   if (op === "!=") return !equals(a, b);
-  if (a == null || b == null) return false;
+  const c = compare(a, b);
+  if (c === undefined) return false;
   switch (op) {
-    case "<": return (a as never) < (b as never);
-    case "<=": return (a as never) <= (b as never);
-    case ">": return (a as never) > (b as never);
-    case ">=": return (a as never) >= (b as never);
+    case "<": return c < 0;
+    case "<=": return c <= 0;
+    case ">": return c > 0;
+    case ">=": return c >= 0;
     default: throw new Error(`not a relational operator: ${op}`);
   }
 }
 
-/** Arithmetic. `+` concatenates when either side is a string. */
+/** The string form of a scalar (the text `+` concatenates and `.lower()` maps):
+ * a string is itself; a number renders as a double with no fraction when
+ * integer-valued (`-0` is `"0"`); booleans are the words. Absent has no string
+ * form (`undefined`), so the operation using it yields absent. */
+export function stringForm(v: unknown): string | undefined {
+  if (v == null) return undefined;
+  if (typeof v === "string") return v;
+  return String(v);
+}
+
+/** Arithmetic. An absent operand makes the result absent; `+` concatenates the
+ * string forms when either side is a string. */
 export function arith(op: string, a: unknown, b: unknown): unknown {
-  if (op === "+" && (typeof a === "string" || typeof b === "string")) return String(a) + String(b);
+  if (a == null || b == null) return undefined;
+  if (op === "+" && (typeof a === "string" || typeof b === "string")) return stringForm(a)! + stringForm(b)!;
   const x = toNumber(a);
   const y = toNumber(b);
   switch (op) {
@@ -57,8 +100,8 @@ export function membership(needle: unknown, haystack: unknown): boolean {
   if (haystack == null) return false;
   if (isRange(haystack)) return rangeCovers(haystack, needle);
   if (Array.isArray(haystack)) return haystack.some((x) => equals(x, needle));
-  if (typeof haystack === "string") return haystack.includes(String(needle));
-  if (typeof haystack === "object") return String(needle) in (haystack as object);
+  if (typeof haystack === "string") { const s = stringForm(needle); return s !== undefined && haystack.includes(s); }
+  if (typeof haystack === "object") { const s = stringForm(needle); return s !== undefined && Object.hasOwn(haystack, s); }
   return false;
 }
 
@@ -84,12 +127,13 @@ export function isRange(v: unknown): v is OqxRange {
 }
 
 /** Whether `x` falls within `range`: `lo <= x` (when lo is present) and either
- * `x <= hi` (inclusive) or `x < hi` (exclusive end) (when hi is present). Bound
- * checks go through `relate`, so an absent `x` — or one that doesn't order
- * against a bound (mixed types) — is simply not covered (never throws). This
- * also makes date/time ranges work over ISO-8601 strings or `Date` values,
- * whose natural ordering `relate` already honors. */
+ * `x <= hi` (inclusive) or `x < hi` (exclusive end) (when hi is present). Only a
+ * number or a string can be covered — an absent `x` is covered by no range, not
+ * even a fully open one — and bound checks go through `relate`, so an `x` that
+ * doesn't order against a bound (mixed types) is simply not covered (never
+ * throws). ISO-8601 strings therefore make date ranges work. */
 export function rangeCovers(range: OqxRange, x: unknown): boolean {
+  if (typeof x !== "number" && typeof x !== "string") return false;
   const geLo = range.lo == null || relate(">=", x, range.lo);
   const leHi = range.hi == null || relate(range.exclusiveEnd ? "<" : "<=", x, range.hi);
   return geLo && leHi;
@@ -103,13 +147,25 @@ export function toNumber(v: unknown): number {
   return typeof v === "number" ? v : Number(v);
 }
 
+/** `size(x)`: a string's code-point count, an array's length, an object's own
+ * key count; absent and other scalars are 0. */
 export function sizeOf(v: unknown): number {
   if (v == null) return 0;
-  if (typeof v === "string" || Array.isArray(v)) return v.length;
+  if (typeof v === "string") return codePointCount(v);
+  if (Array.isArray(v)) return v.length;
   if (typeof v === "object") return Object.keys(v).length;
   return 0;
 }
 
+function codePointCount(s: string): number {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    n++;
+    if (s.codePointAt(i)! > 0xffff) i++;
+  }
+  return n;
+}
+
 export function toList(v: unknown): unknown[] {
   if (v == null) return [];
   if (Array.isArray(v)) return v;
@@ -131,15 +187,38 @@ export function coerceCollection(v: unknown): unknown[] {
   return [v];
 }
 
-/** Total order for `order by`, with absent values sorting last. */
+/** Order for `order by`: absent values sort last; present values order by
+ * `compare` (numbers numerically, strings by code point); a pair that does not
+ * order (mixed types, booleans) is left where it is (compares equal). */
 export function compareForSort(a: unknown, b: unknown): number {
   const an = a == null, bn = b == null;
   if (an && bn) return 0;
   if (an) return 1;
   if (bn) return -1;
-  if ((a as never) < (b as never)) return -1;
-  if ((a as never) > (b as never)) return 1;
-  return 0;
+  return compare(a, b) ?? 0;
+}
+
+// ---- structural identity ----------------------------------------------------
+
+/** A canonical, type-tagged serialization of a value, used wherever OQX needs a
+ * value's IDENTITY as a key (`follow` cycle detection and dedup, `distinct`):
+ * two values get the same key iff they are structurally equal — absent ≡ null,
+ * numbers as doubles (`-0` ≡ `0`), object key order ignored. The type tags keep
+ * `1`, `"1"`, and `true` apart, and `{}`/`[]` apart from every scalar. */
+export function canonicalKey(v: unknown): string {
+  if (v == null) return "n";
+  switch (typeof v) {
+    case "boolean": return v ? "t" : "f";
+    case "number": return `d${v === 0 ? 0 : v}`;
+    case "string": return `s${JSON.stringify(v)}`;
+    case "object": {
+      if (Array.isArray(v)) return `[${v.map(canonicalKey).join(",")}]`;
+      if (isEntry(v)) return canonicalKey(v.value);
+      const o = v as Record<string, unknown>;
+      return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalKey(o[k])}`).join(",")}}`;
+    }
+    default: return `?${String(v)}`;
+  }
 }
 
 /** Parse a string as a range value (`1..5`, `1...5`, `..5`, `5..`, or an
@@ -219,17 +298,35 @@ export const BUILTIN_FUNCTIONS: Record<string, (args: unknown[]) => unknown> = {
   range: (args) => (isRange(args[0]) ? args[0] : typeof args[0] === "string" ? parseRangeString(args[0]) : null),
 };
 
+// ---- regex: the OQX baseline ------------------------------------------------
+//
+// `matches(pattern, flags)` compiles the pattern in the OQX regex baseline (see
+// regex.ts): a fixed grammar with spec-pinned semantics, rejected up front when
+// it uses anything else, so every pattern that runs is portable. A host may opt
+// into its engine's native dialect through `DataContext.regexDialect`.
+
+export { compileRegex, parseRegexFlags } from "./regex.ts";
+export type { RegexDialect, RegexFlags } from "./regex.ts";
+
+/** `recv.matches(pattern, flags?)`: false for an absent receiver; otherwise
+ * whether the pattern (compiled in `dialect`) matches anywhere in the
+ * receiver's string form. Bad flags or a bad pattern are eval errors. */
+export function regexMatches(recv: unknown, args: unknown[], dialect: RegexDialect = "oqx"): boolean {
+  const s = stringForm(recv);
+  return s !== undefined && compileRegex(String(args[0]), args[1], dialect).test(s);
+}
+
 /** Methods callable as `recv.name(args)`. */
 export const BUILTIN_METHODS: Record<string, (recv: unknown, args: unknown[]) => unknown> = {
   contains: (recv, args) => {
-    if (typeof recv === "string") return recv.includes(String(args[0]));
+    if (typeof recv === "string") { const s = stringForm(args[0]); return s !== undefined && recv.includes(s); }
     if (Array.isArray(recv)) return recv.some((x) => equals(x, args[0]));
     return false;
   },
-  startsWith: (recv, args) => typeof recv === "string" && recv.startsWith(String(args[0])),
-  endsWith: (recv, args) => typeof recv === "string" && recv.endsWith(String(args[0])),
-  matches: (recv, args) => recv != null && new RegExp(String(args[0])).test(String(recv)),
+  startsWith: (recv, args) => { const s = stringForm(args[0]); return typeof recv === "string" && s !== undefined && recv.startsWith(s); },
+  endsWith: (recv, args) => { const s = stringForm(args[0]); return typeof recv === "string" && s !== undefined && recv.endsWith(s); },
+  matches: (recv, args) => regexMatches(recv, args, "oqx"),
   size: (recv) => sizeOf(recv),
-  lower: (recv) => String(recv).toLowerCase(),
-  upper: (recv) => String(recv).toUpperCase(),
+  lower: (recv) => stringForm(recv)?.toLowerCase(),
+  upper: (recv) => stringForm(recv)?.toUpperCase(),
 };