@columnus/shared 0.1.47

package/dist/queryFieldOps.d.ts

@@ -0,0 +1,66 @@
+import type { FieldType, Table } from "./schemaTypes.ts";
+/** One edit surface for each predicate operation's wire shape and UI label. */
+export declare const PREDICATE_VARIANTS: readonly [{
+    readonly value: "unknown";
+    readonly ops: readonly [{
+        readonly op: "eq";
+        readonly label: "=";
+    }, {
+        readonly op: "neq";
+        readonly label: "≠";
+    }];
+}, {
+    readonly value: "unknownArray";
+    readonly ops: readonly [{
+        readonly op: "in";
+        readonly label: "in";
+    }];
+}, {
+    readonly value: "unknown";
+    readonly ops: readonly [{
+        readonly op: "gt";
+        readonly label: ">";
+    }, {
+        readonly op: "gte";
+        readonly label: "≥";
+    }, {
+        readonly op: "lt";
+        readonly label: "<";
+    }, {
+        readonly op: "lte";
+        readonly label: "≤";
+    }];
+}, {
+    readonly value: "between";
+    readonly ops: readonly [{
+        readonly op: "between";
+        readonly label: "between";
+    }];
+}, {
+    readonly value: "unknownArray";
+    readonly ops: readonly [{
+        readonly op: "containsAll";
+        readonly label: "contains all";
+    }];
+}];
+type PredicateOperator = (typeof PREDICATE_VARIANTS)[number]["ops"][number];
+export type PredicateOp = PredicateOperator["op"];
+export declare const PREDICATE_OPS: PredicateOp[];
+export declare function predicateOpLabel(op: PredicateOp): string;
+export type FieldOpSupport = {
+    eq: boolean;
+    neq: boolean;
+    in: boolean;
+    ranges: boolean;
+    sort: boolean;
+    containsAll: boolean;
+};
+/** Resolve field type for user fields and system fields (`_id`, `_creationTime`). */
+export declare function resolveQueryFieldType(table: Pick<Table, "name" | "fields">, field: string): FieldType | null;
+/** Effective type used for operator eligibility (unwraps homogeneous unions). */
+export declare function effectiveQueryFieldType(t: FieldType): FieldType | null;
+export declare function fieldOpSupport(type: FieldType): FieldOpSupport;
+export declare function opAllowedForType(type: FieldType, op: PredicateOp): boolean;
+export declare function fieldSupportsSort(type: FieldType): boolean;
+export declare function isRangeOp(op: PredicateOp): boolean;
+export {};

package/dist/queryFieldOps.js

@@ -0,0 +1,138 @@
+// packages/@columnus/shared/src/queryFieldOps.ts
+var PREDICATE_VARIANTS = [
+  {
+    value: "unknown",
+    ops: [
+      { op: "eq", label: "=" },
+      { op: "neq", label: "\u2260" }
+    ]
+  },
+  { value: "unknownArray", ops: [{ op: "in", label: "in" }] },
+  {
+    value: "unknown",
+    ops: [
+      { op: "gt", label: ">" },
+      { op: "gte", label: "\u2265" },
+      { op: "lt", label: "<" },
+      { op: "lte", label: "\u2264" }
+    ]
+  },
+  { value: "between", ops: [{ op: "between", label: "between" }] },
+  {
+    value: "unknownArray",
+    ops: [{ op: "containsAll", label: "contains all" }]
+  }
+];
+var PREDICATE_OPS = PREDICATE_VARIANTS.flatMap(
+  (variant) => variant.ops.map(({ op }) => op)
+);
+var PREDICATE_OP_LABELS = new Map(
+  PREDICATE_VARIANTS.flatMap((variant) => variant.ops.map(({ op, label }) => [op, label]))
+);
+function predicateOpLabel(op) {
+  return PREDICATE_OP_LABELS.get(op) ?? op;
+}
+var NONE = {
+  eq: false,
+  neq: false,
+  in: false,
+  ranges: false,
+  sort: false,
+  containsAll: false
+};
+var SCALAR_ORDERED = {
+  eq: true,
+  neq: true,
+  in: true,
+  ranges: true,
+  sort: true,
+  containsAll: false
+};
+var SCALAR_EQ = {
+  eq: true,
+  neq: true,
+  in: true,
+  ranges: false,
+  sort: true,
+  containsAll: false
+};
+function resolveQueryFieldType(table, field) {
+  if (field === "_id") return { kind: "id", table: table.name };
+  if (field === "_creationTime") return { kind: "number" };
+  return table.fields.find((f) => f.name === field)?.type ?? null;
+}
+function comparableUnionKind(t) {
+  if (t.kind !== "union" || t.options.length === 0) return null;
+  const first = t.options[0];
+  if (!t.options.every((o) => o.kind === first.kind)) return null;
+  if (first.kind === "string" || first.kind === "number" || first.kind === "bigint" || first.kind === "boolean" || first.kind === "date" || first.kind === "datetime" || first.kind === "id") {
+    return first;
+  }
+  if (first.kind === "literal") {
+    const v = first.value;
+    if (typeof v === "string") return { kind: "string" };
+    if (typeof v === "number") return { kind: "number" };
+    if (typeof v === "boolean") return { kind: "boolean" };
+  }
+  return null;
+}
+function effectiveQueryFieldType(t) {
+  if (t.kind === "union") return comparableUnionKind(t);
+  return t;
+}
+function fieldOpSupport(type) {
+  const t = effectiveQueryFieldType(type);
+  if (!t) return NONE;
+  switch (t.kind) {
+    case "string":
+    case "number":
+    case "bigint":
+    case "date":
+    case "datetime":
+      return SCALAR_ORDERED;
+    case "boolean":
+    case "id":
+    case "literal":
+      return SCALAR_EQ;
+    case "array":
+      if (t.element.kind === "id" || t.element.kind === "string" || t.element.kind === "number" || t.element.kind === "boolean" || t.element.kind === "literal") {
+        return { ...NONE, containsAll: true };
+      }
+      return NONE;
+    default:
+      return NONE;
+  }
+}
+function opAllowedForType(type, op) {
+  const support = fieldOpSupport(type);
+  switch (op) {
+    case "eq":
+      return support.eq;
+    case "neq":
+      return support.neq;
+    case "in":
+      return support.in;
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte":
+    case "between":
+      return support.ranges;
+    case "containsAll":
+      return support.containsAll;
+    default: {
+      const _exhaustive = op;
+      return _exhaustive;
+    }
+  }
+}
+function fieldSupportsSort(type) {
+  return fieldOpSupport(type).sort;
+}
+function isRangeOp(op) {
+  return op === "gt" || op === "gte" || op === "lt" || op === "lte" || op === "between";
+}
+
+export { PREDICATE_OPS, PREDICATE_VARIANTS, effectiveQueryFieldType, fieldOpSupport, fieldSupportsSort, isRangeOp, opAllowedForType, predicateOpLabel, resolveQueryFieldType };
+//# sourceMappingURL=queryFieldOps.js.map
+//# sourceMappingURL=queryFieldOps.js.map

package/dist/queryFieldOps.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/queryFieldOps.ts"],"names":[],"mappings":"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","file":"queryFieldOps.js","sourcesContent":["import type { FieldType, Table } from \"./schemaTypes.ts\";\n\n/** One edit surface for each predicate operation's wire shape and UI label. */\nexport const PREDICATE_VARIANTS = [\n  {\n    value: \"unknown\",\n    ops: [\n      { op: \"eq\", label: \"=\" },\n      { op: \"neq\", label: \"≠\" },\n    ],\n  },\n  { value: \"unknownArray\", ops: [{ op: \"in\", label: \"in\" }] },\n  {\n    value: \"unknown\",\n    ops: [\n      { op: \"gt\", label: \">\" },\n      { op: \"gte\", label: \"≥\" },\n      { op: \"lt\", label: \"<\" },\n      { op: \"lte\", label: \"≤\" },\n    ],\n  },\n  { value: \"between\", ops: [{ op: \"between\", label: \"between\" }] },\n  {\n    value: \"unknownArray\",\n    ops: [{ op: \"containsAll\", label: \"contains all\" }],\n  },\n] as const;\n\ntype PredicateOperator = (typeof PREDICATE_VARIANTS)[number][\"ops\"][number];\nexport type PredicateOp = PredicateOperator[\"op\"];\nexport const PREDICATE_OPS = PREDICATE_VARIANTS.flatMap((variant) =>\n  variant.ops.map(({ op }) => op),\n) as PredicateOp[];\n\nconst PREDICATE_OP_LABELS = new Map<PredicateOp, string>(\n  PREDICATE_VARIANTS.flatMap((variant) => variant.ops.map(({ op, label }) => [op, label] as const)),\n);\n\nexport function predicateOpLabel(op: PredicateOp): string {\n  return PREDICATE_OP_LABELS.get(op) ?? op;\n}\n\nexport type FieldOpSupport = {\n  eq: boolean;\n  neq: boolean;\n  in: boolean;\n  ranges: boolean;\n  sort: boolean;\n  containsAll: boolean;\n};\n\nconst NONE: FieldOpSupport = {\n  eq: false,\n  neq: false,\n  in: false,\n  ranges: false,\n  sort: false,\n  containsAll: false,\n};\n\nconst SCALAR_ORDERED: FieldOpSupport = {\n  eq: true,\n  neq: true,\n  in: true,\n  ranges: true,\n  sort: true,\n  containsAll: false,\n};\n\nconst SCALAR_EQ: FieldOpSupport = {\n  eq: true,\n  neq: true,\n  in: true,\n  ranges: false,\n  sort: true,\n  containsAll: false,\n};\n\n/** Resolve field type for user fields and system fields (`_id`, `_creationTime`). */\nexport function resolveQueryFieldType(\n  table: Pick<Table, \"name\" | \"fields\">,\n  field: string,\n): FieldType | null {\n  if (field === \"_id\") return { kind: \"id\", table: table.name };\n  if (field === \"_creationTime\") return { kind: \"number\" };\n  return table.fields.find((f) => f.name === field)?.type ?? null;\n}\n\nfunction comparableUnionKind(t: FieldType): FieldType | null {\n  if (t.kind !== \"union\" || t.options.length === 0) return null;\n  const first = t.options[0]!;\n  if (!t.options.every((o) => o.kind === first.kind)) return null;\n  if (\n    first.kind === \"string\" ||\n    first.kind === \"number\" ||\n    first.kind === \"bigint\" ||\n    first.kind === \"boolean\" ||\n    first.kind === \"date\" ||\n    first.kind === \"datetime\" ||\n    first.kind === \"id\"\n  ) {\n    return first;\n  }\n  if (first.kind === \"literal\") {\n    const v = first.value;\n    if (typeof v === \"string\") return { kind: \"string\" };\n    if (typeof v === \"number\") return { kind: \"number\" };\n    if (typeof v === \"boolean\") return { kind: \"boolean\" };\n  }\n  return null;\n}\n\n/** Effective type used for operator eligibility (unwraps homogeneous unions). */\nexport function effectiveQueryFieldType(t: FieldType): FieldType | null {\n  if (t.kind === \"union\") return comparableUnionKind(t);\n  return t;\n}\n\nexport function fieldOpSupport(type: FieldType): FieldOpSupport {\n  const t = effectiveQueryFieldType(type);\n  if (!t) return NONE;\n\n  switch (t.kind) {\n    case \"string\":\n    case \"number\":\n    case \"bigint\":\n    case \"date\":\n    case \"datetime\":\n      return SCALAR_ORDERED;\n    case \"boolean\":\n    case \"id\":\n    case \"literal\":\n      return SCALAR_EQ;\n    case \"array\":\n      if (\n        t.element.kind === \"id\" ||\n        t.element.kind === \"string\" ||\n        t.element.kind === \"number\" ||\n        t.element.kind === \"boolean\" ||\n        t.element.kind === \"literal\"\n      ) {\n        return { ...NONE, containsAll: true };\n      }\n      return NONE;\n    default:\n      return NONE;\n  }\n}\n\nexport function opAllowedForType(type: FieldType, op: PredicateOp): boolean {\n  const support = fieldOpSupport(type);\n  switch (op) {\n    case \"eq\":\n      return support.eq;\n    case \"neq\":\n      return support.neq;\n    case \"in\":\n      return support.in;\n    case \"gt\":\n    case \"gte\":\n    case \"lt\":\n    case \"lte\":\n    case \"between\":\n      return support.ranges;\n    case \"containsAll\":\n      return support.containsAll;\n    default: {\n      const _exhaustive: never = op;\n      return _exhaustive;\n    }\n  }\n}\n\nexport function fieldSupportsSort(type: FieldType): boolean {\n  return fieldOpSupport(type).sort;\n}\n\nexport function isRangeOp(op: PredicateOp): boolean {\n  return op === \"gt\" || op === \"gte\" || op === \"lt\" || op === \"lte\" || op === \"between\";\n}\n"]}

package/dist/queryMerge.d.ts

@@ -0,0 +1,29 @@
+import { type ClampQuery, type Predicate, type Query, type QueryError } from "./queryTypes.ts";
+export type MergedQuery = {
+    /** Logical caller query after predicate/default merge; preserves explicit caller options. */
+    query: Query;
+    /** Execution ceiling after applying the profile/share limit to the caller request. */
+    effectiveMaxScan: number;
+};
+export type MergeQueryInput = {
+    caller?: Query | null;
+    clamp?: ClampQuery | null;
+    /** Profile/share ceiling; defaults to {@link DEFAULT_MAX_SCAN_LIMIT}. */
+    maxScanLimit?: number;
+};
+export declare function predicatesEqual(a: Predicate, b: Predicate): boolean;
+/** Detect contradictory equality / membership on the same field. */
+export declare function findUnsatisfiablePredicates(predicates: Predicate[]): QueryError | null;
+/**
+ * AND-merge clamp with caller query.
+ * Clamp supplies defaults for order/search; caller may override.
+ * The caller's optional `maxScan` stays in the AST; `effectiveMaxScan` applies the ceiling.
+ * `indexHint` comes from the caller only.
+ */
+export declare function mergeQuery(input: MergeQueryInput): {
+    ok: true;
+    merged: MergedQuery;
+} | {
+    ok: false;
+    error: QueryError;
+};