equipped 5.2.8 → 5.3.0-alpha.0

package/dist/esm/chunk-TWKHVLLT.mjs

@@ -0,0 +1,1280 @@
+import {
+  EquippedError,
+  Instance
+} from "./chunk-2TCFNKRZ.mjs";
+
+// src/orm/errors/validation.ts
+var OrmValidationError = class extends EquippedError {
+  constructor(kind, schema, operation, failures) {
+    super(`ORM validation error (${kind}) on ${schema}.${operation}`, {
+      kind,
+      schema,
+      operation,
+      failures
+    });
+    this.kind = kind;
+    this.schema = schema;
+    this.operation = operation;
+    this.failures = failures;
+  }
+};
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  const { EquippedError: EquippedError2 } = await null;
+  describe("OrmValidationError", () => {
+    test("constructs with aggregate kind", () => {
+      const err = new OrmValidationError("aggregate", "orders", "aggregate", []);
+      expect(err.kind).toBe("aggregate");
+      expect(err.operation).toBe("aggregate");
+      expect(err.message).toBe("ORM validation error (aggregate) on orders.aggregate");
+      expect(err).toBeInstanceOf(OrmValidationError);
+      expect(err).toBeInstanceOf(EquippedError2);
+    });
+    test("failure carries alias through to context", () => {
+      const failures = [
+        { alias: "total_price", cause: "alias collision" }
+      ];
+      const err = new OrmValidationError("aggregate", "orders", "aggregate", failures);
+      expect(err.failures[0].alias).toBe("total_price");
+      expect(err.context.failures[0].alias).toBe("total_price");
+    });
+    test("failure without alias still works", () => {
+      const failures = [
+        { field: "amount", cause: "invalid field" }
+      ];
+      const err = new OrmValidationError("validation", "orders", "createOne", failures);
+      expect(err.failures[0].alias).toBeUndefined();
+      expect(err.failures[0].field).toBe("amount");
+    });
+    test.each([
+      "validation",
+      "conflicting-ops",
+      "empty-group",
+      "undeclared-op",
+      "upsert-filter-incompatible",
+      "query-shape",
+      "changes"
+    ])("kind %s still works", (kind) => {
+      const err = new OrmValidationError(kind, "users", "createOne", []);
+      expect(err.kind).toBe(kind);
+    });
+  });
+}
+
+// src/orm/fields.ts
+import "valleyed";
+var Field = class {
+  name;
+  path;
+  constructor(name, path) {
+    this.name = name;
+    this.path = path ?? [name];
+  }
+};
+function toFieldName(field) {
+  if (field instanceof Field) return field.path.join(".");
+  return field;
+}
+var SchemaField = class extends Field {
+  pipe;
+  onCreate;
+  onUpdate;
+  constructor(name, pipe, opts) {
+    super(name);
+    this.pipe = pipe;
+    this.onCreate = opts?.onCreate;
+    this.onUpdate = opts?.onUpdate;
+  }
+};
+var ComputedField = class {
+  constructor(name, pipe, deps, compute) {
+    this.name = name;
+    this.pipe = pipe;
+    this.deps = deps;
+    this.compute = compute;
+  }
+};
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  describe("Fields", () => {
+    describe("Field", () => {
+      test("stores name and defaults path to [name]", () => {
+        const f = new Field("email");
+        expect(f.name).toBe("email");
+        expect(f.path).toEqual(["email"]);
+      });
+      test("stores provided custom path", () => {
+        const f = new Field("profile", ["profile", "displayName"]);
+        expect(f.name).toBe("profile");
+        expect(f.path).toEqual(["profile", "displayName"]);
+      });
+    });
+    describe("toFieldName()", () => {
+      test("returns string input unchanged", () => {
+        expect(toFieldName("createdAt")).toBe("createdAt");
+      });
+      test("converts Field path into dot notation", () => {
+        const f = new Field("profile", ["profile", "displayName"]);
+        expect(toFieldName(f)).toBe("profile.displayName");
+      });
+    });
+    describe("SchemaField", () => {
+      test("extends Field and stores pipe", () => {
+        const mockPipe = v.string();
+        const f = new SchemaField("email", mockPipe);
+        expect(f).toBeInstanceOf(Field);
+        expect(f.name).toBe("email");
+        expect(f.path).toEqual(["email"]);
+        expect(f.pipe).toBe(mockPipe);
+      });
+      test("stores lifecycle hooks when provided", () => {
+        const mockPipe = v.number();
+        const f = new SchemaField("updatedAt", mockPipe, {
+          onCreate: () => 1e3,
+          onUpdate: () => 2e3
+        });
+        expect(f.onCreate?.()).toBe(1e3);
+        expect(f.onUpdate?.()).toBe(2e3);
+      });
+      test("keeps lifecycle hooks undefined when omitted", () => {
+        const mockPipe = v.string();
+        const f = new SchemaField("name", mockPipe);
+        expect(f.onCreate).toBeUndefined();
+        expect(f.onUpdate).toBeUndefined();
+      });
+    });
+  });
+}
+
+// src/orm/filter.ts
+var Filter = class {
+  constructor(field, op, value) {
+    this.op = op;
+    this.value = value;
+    this.field = toFieldName(field);
+  }
+  field;
+};
+var FilterGroup = class _FilterGroup {
+  constructor(op = "and", children) {
+    this.op = op;
+    this.children = children ?? [];
+  }
+  children;
+  #withChild(child) {
+    return new _FilterGroup(this.op, [...this.children, child]);
+  }
+  eq(field, value) {
+    return this.#withChild(new Filter(field, "eq", value));
+  }
+  ne(field, value) {
+    return this.#withChild(new Filter(field, "ne", value));
+  }
+  gt(field, value) {
+    return this.#withChild(new Filter(field, "gt", value));
+  }
+  gte(field, value) {
+    return this.#withChild(new Filter(field, "gte", value));
+  }
+  lt(field, value) {
+    return this.#withChild(new Filter(field, "lt", value));
+  }
+  lte(field, value) {
+    return this.#withChild(new Filter(field, "lte", value));
+  }
+  in(field, value) {
+    return this.#withChild(new Filter(field, "in", value));
+  }
+  notIn(field, value) {
+    return this.#withChild(new Filter(field, "notIn", value));
+  }
+  like(field, value) {
+    return this.#withChild(new Filter(field, "like", value));
+  }
+  exists(field) {
+    return this.#withChild(new Filter(field, "exists", true));
+  }
+  notExists(field) {
+    return this.#withChild(new Filter(field, "notExists", true));
+  }
+  contains(field, value) {
+    return this.#withChild(new Filter(field, "contains", value));
+  }
+  notContains(field, value) {
+    return this.#withChild(new Filter(field, "notContains", value));
+  }
+  and(facFns) {
+    if (facFns.length === 0) throw new EquippedError("and() requires at least one filter factory", { op: "and" });
+    const group = new _FilterGroup("and", facFns.map((fn) => fn(_FilterGroup.create())));
+    return this.#withChild(group);
+  }
+  or(facFns) {
+    if (facFns.length === 0) throw new EquippedError("or() requires at least one filter factory", { op: "or" });
+    const group = new _FilterGroup("or", facFns.map((fn) => fn(_FilterGroup.create())));
+    return this.#withChild(group);
+  }
+  clone() {
+    return new _FilterGroup(
+      this.op,
+      this.children.map((c) => {
+        if (c instanceof Filter) return new Filter(c.field, c.op, structuredClone(c.value));
+        return c.clone();
+      })
+    );
+  }
+  static create() {
+    return new _FilterGroup();
+  }
+};
+function assertNormalisedAggregate(schema, adapter, spec) {
+  const failures = [];
+  if (spec.aggregates.length === 0) {
+    failures.push({ cause: "At least one aggregator step is required" });
+  }
+  const seenAliases = /* @__PURE__ */ new Set();
+  for (const agg of spec.aggregates) {
+    if (seenAliases.has(agg.alias)) {
+      failures.push({ alias: agg.alias, cause: `Duplicate alias "${agg.alias}"` });
+    }
+    seenAliases.add(agg.alias);
+    if (!adapter.aggregateOps.includes(agg.fn)) {
+      failures.push({ alias: agg.alias, cause: `Undeclared aggregate op "${agg.fn}"` });
+    }
+  }
+  const allFields = schema.fields;
+  const fieldNames = new Set(Object.keys(allFields));
+  for (const field of spec.groupBy) {
+    if (!fieldNames.has(field)) {
+      failures.push({ field, cause: `Unknown groupBy field "${field}" on schema "${schema.name}"` });
+    }
+    if (seenAliases.has(field)) {
+      failures.push({ alias: field, cause: `Alias "${field}" collides with groupBy field name` });
+    }
+  }
+  if (failures.length > 0) {
+    throw new OrmValidationError("aggregate", schema.name, "aggregate", failures);
+  }
+  if (spec.where) {
+    assertNormalisedFilter(schema, spec.where);
+  }
+  if (spec.having) {
+    let walkHaving2 = function(node) {
+      if (node instanceof Filter) {
+        if (!validHavingFields.has(node.field)) {
+          havingErrors.push({ field: node.field, cause: `Unknown having field "${node.field}" \u2014 must be an aggregator alias or groupBy field` });
+        }
+      } else if (node instanceof FilterGroup) {
+        for (const child of node.children) walkHaving2(child);
+      }
+    };
+    var walkHaving = walkHaving2;
+    const validHavingFields = /* @__PURE__ */ new Set([...seenAliases, ...spec.groupBy]);
+    const havingErrors = [];
+    for (const child of spec.having.children) walkHaving2(child);
+    if (havingErrors.length > 0) {
+      throw new OrmValidationError("aggregate", schema.name, "aggregate", havingErrors);
+    }
+  }
+}
+function assertNormalisedFilter(schema, group) {
+  const allFields = schema.fields;
+  const fieldNames = new Set(Object.keys(allFields));
+  const errors = [];
+  function walk(node) {
+    if (node instanceof Filter) {
+      if (!fieldNames.has(node.field)) {
+        errors.push({ field: node.field, cause: `Unknown field "${node.field}" on schema "${schema.name}"` });
+      }
+    } else if (node instanceof FilterGroup) {
+      for (const child of node.children) walk(child);
+    }
+  }
+  for (const child of group.children) walk(child);
+  if (errors.length > 0) {
+    throw new OrmValidationError(
+      "validation",
+      schema.name,
+      "filter",
+      errors.map((e) => ({ field: e.field, cause: e.cause }))
+    );
+  }
+}
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  const { v: v2 } = await null;
+  const { Schema } = await null;
+  const UserSchema = Schema.from("users").pk("id", v2.string(), () => "u1").field("email", v2.string()).field("age", v2.number()).field("name", v2.string()).field("tags", v2.array(v2.string())).build();
+  describe("FilterGroup", () => {
+    describe("filter-op methods", () => {
+      test("eq adds a filter clause with op eq", () => {
+        const g = FilterGroup.create().eq(UserSchema.fields.age, 25);
+        expect(g.children).toHaveLength(1);
+        const f = g.children[0];
+        expect(f.field).toBe("age");
+        expect(f.op).toBe("eq");
+        expect(f.value).toBe(25);
+      });
+      test("ne adds a filter clause with op ne", () => {
+        const g = FilterGroup.create().ne("name", "Bob");
+        const f = g.children[0];
+        expect(f.op).toBe("ne");
+        expect(f.value).toBe("Bob");
+      });
+      test("gt/gte/lt/lte produce correct ops", () => {
+        const g = FilterGroup.create().gt(UserSchema.fields.age, 10).gte(UserSchema.fields.age, 20).lt(UserSchema.fields.age, 30).lte(UserSchema.fields.age, 40);
+        expect(g.children.map((c) => c.op)).toEqual(["gt", "gte", "lt", "lte"]);
+      });
+      test("in adds a filter clause with array value", () => {
+        const g = FilterGroup.create().in(UserSchema.fields.age, [1, 2, 3]);
+        const f = g.children[0];
+        expect(f.op).toBe("in");
+        expect(f.value).toEqual([1, 2, 3]);
+      });
+      test("notIn adds a filter clause with op notIn", () => {
+        const g = FilterGroup.create().notIn(UserSchema.fields.age, [4, 5]);
+        const f = g.children[0];
+        expect(f.op).toBe("notIn");
+        expect(f.value).toEqual([4, 5]);
+      });
+      test("like adds a filter clause with op like", () => {
+        const g = FilterGroup.create().like(UserSchema.fields.email, "alice");
+        const f = g.children[0];
+        expect(f.op).toBe("like");
+        expect(f.value).toBe("alice");
+      });
+      test("exists adds a filter clause with op exists", () => {
+        const g = FilterGroup.create().exists(UserSchema.fields.name);
+        const f = g.children[0];
+        expect(f.op).toBe("exists");
+      });
+      test("notExists is its own op, not a boolean form of exists", () => {
+        const g = FilterGroup.create().notExists(UserSchema.fields.name);
+        const f = g.children[0];
+        expect(f.op).toBe("notExists");
+        expect(f.op).not.toBe("exists");
+      });
+      test("contains/notContains produce correct ops", () => {
+        const g = FilterGroup.create().contains("tags", ["a"]).notContains("tags", ["b"]);
+        expect(g.children[0].op).toBe("contains");
+        expect(g.children[1].op).toBe("notContains");
+      });
+      test("all 13 filter ops produce matching Filter.op values (name-parity)", () => {
+        const g = FilterGroup.create().eq("f", 1).ne("f", 1).gt("f", 1).gte("f", 1).lt("f", 1).lte("f", 1).in("f", [1]).notIn("f", [1]).like("f", "x").exists("f").notExists("f").contains("f", [1]).notContains("f", [1]);
+        const ops = g.children.map((c) => c.op);
+        expect(ops).toEqual([
+          "eq",
+          "ne",
+          "gt",
+          "gte",
+          "lt",
+          "lte",
+          "in",
+          "notIn",
+          "like",
+          "exists",
+          "notExists",
+          "contains",
+          "notContains"
+        ]);
+      });
+    });
+    describe("raw-string field overload", () => {
+      test("accepts raw string field name", () => {
+        const g = FilterGroup.create().eq("age", 18);
+        const f = g.children[0];
+        expect(f.field).toBe("age");
+      });
+      test("accepts typed Field ref and extracts field name", () => {
+        const g = FilterGroup.create().eq(UserSchema.fields.age, 18);
+        const f = g.children[0];
+        expect(f.field).toBe("age");
+      });
+    });
+    describe("structural combinators", () => {
+      test("and() creates a nested and-group", () => {
+        const g = FilterGroup.create().and([
+          (q) => q.eq("age", 10),
+          (q) => q.eq("name", "Alice")
+        ]);
+        expect(g.children).toHaveLength(1);
+        const nested = g.children[0];
+        expect(nested.op).toBe("and");
+        expect(nested.children).toHaveLength(2);
+      });
+      test("or() creates a nested or-group", () => {
+        const g = FilterGroup.create().or([
+          (q) => q.eq("name", "Alice"),
+          (q) => q.eq("name", "Bob")
+        ]);
+        const nested = g.children[0];
+        expect(nested.op).toBe("or");
+      });
+    });
+    describe("empty-combinator rejection", () => {
+      test("and([]) throws at builder time", () => {
+        expect(() => FilterGroup.create().and([])).toThrow();
+      });
+      test("or([]) throws at builder time", () => {
+        expect(() => FilterGroup.create().or([])).toThrow();
+      });
+      test("thrown error has stack pointing at offending call", () => {
+        try {
+          FilterGroup.create().and([]);
+          expect.unreachable();
+        } catch (e) {
+          expect(e.stack).toContain("filter.ts");
+        }
+      });
+    });
+    describe("clone()", () => {
+      test("deep-clones the tree", () => {
+        const original = FilterGroup.create().eq("name", "Alice").and([(q) => q.gt("age", 20)]);
+        const cloned = original.clone();
+        expect(cloned.children).toHaveLength(2);
+        expect(cloned).not.toBe(original);
+        expect(cloned.children[0]).not.toBe(original.children[0]);
+      });
+      test("structuredClone of values \u2014 mutations on clone do not leak", () => {
+        const arr = [1, 2, 3];
+        const original = FilterGroup.create().in("ids", arr);
+        const cloned = original.clone();
+        const clonedValue = cloned.children[0].value;
+        clonedValue.push(4);
+        expect(original.children[0].value).toEqual([1, 2, 3]);
+        expect(clonedValue).toEqual([1, 2, 3, 4]);
+      });
+    });
+  });
+  describe("clone-on-step: fan-out independence", () => {
+    test(".eq() returns a new FilterGroup, not the same instance", () => {
+      const base = FilterGroup.create();
+      const a = base.eq("name", "Alice");
+      expect(a).not.toBe(base);
+    });
+    test("fan-out from shared base does not pollute either branch", () => {
+      const base = FilterGroup.create().eq("name", "Alice");
+      const branchA = base.gt("age", 20);
+      const branchB = base.lt("age", 40);
+      expect(branchA.children).toHaveLength(2);
+      expect(branchB.children).toHaveLength(2);
+      expect(base.children).toHaveLength(1);
+      expect(branchA.children[1].op).toBe("gt");
+      expect(branchB.children[1].op).toBe("lt");
+    });
+    test(".and() returns a new FilterGroup", () => {
+      const base = FilterGroup.create().eq("name", "Alice");
+      const withAnd = base.and([(q) => q.gt("age", 20)]);
+      expect(withAnd).not.toBe(base);
+      expect(base.children).toHaveLength(1);
+      expect(withAnd.children).toHaveLength(2);
+    });
+    test(".or() returns a new FilterGroup", () => {
+      const base = FilterGroup.create().eq("name", "Alice");
+      const withOr = base.or([(q) => q.gt("age", 20)]);
+      expect(withOr).not.toBe(base);
+      expect(base.children).toHaveLength(1);
+      expect(withOr.children).toHaveLength(2);
+    });
+  });
+  describe("assertNormalisedFilter", () => {
+    test("passes for valid filter referencing known fields", () => {
+      const g = FilterGroup.create().eq(UserSchema.fields.age, 25);
+      expect(() => assertNormalisedFilter(UserSchema, g)).not.toThrow();
+    });
+    test("passes for raw string field that exists on schema", () => {
+      const g = FilterGroup.create().eq("email", "test@test.com");
+      expect(() => assertNormalisedFilter(UserSchema, g)).not.toThrow();
+    });
+    test("rejects unknown field name with OrmValidationError", () => {
+      const g = FilterGroup.create().eq("unknownField", 42);
+      expect(() => assertNormalisedFilter(UserSchema, g)).toThrow(OrmValidationError);
+    });
+    test("rejected error has kind validation", () => {
+      const g = FilterGroup.create().eq("badField", 42);
+      try {
+        assertNormalisedFilter(UserSchema, g);
+        expect.unreachable();
+      } catch (e) {
+        expect(e).toBeInstanceOf(OrmValidationError);
+        expect(e.kind).toBe("validation");
+        expect(e.failures).toHaveLength(1);
+        expect(e.failures[0].field).toBe("badField");
+      }
+    });
+    test("preserves logical field names verbatim for Field refs", () => {
+      const g = FilterGroup.create().eq(UserSchema.fields.email, "a@b.com");
+      const f = g.children[0];
+      expect(f.field).toBe("email");
+      assertNormalisedFilter(UserSchema, g);
+    });
+    test("preserves logical field names verbatim for raw-string overloads", () => {
+      const g = FilterGroup.create().eq("age", 18);
+      const f = g.children[0];
+      expect(f.field).toBe("age");
+      assertNormalisedFilter(UserSchema, g);
+    });
+    test("walks nested groups to detect unknown fields", () => {
+      const g = FilterGroup.create().and([
+        (q) => q.eq("name", "Alice"),
+        (q) => q.or([(inner) => inner.eq("nonexistent", "val")])
+      ]);
+      expect(() => assertNormalisedFilter(UserSchema, g)).toThrow(OrmValidationError);
+    });
+  });
+  describe("assertNormalisedAggregate", () => {
+    const adapter = { aggregateOps: ["count"] };
+    test("passes for valid count aggregate", () => {
+      const spec = { aggregates: [{ fn: "count", alias: "total" }], groupBy: [] };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).not.toThrow();
+    });
+    test("rejects empty aggregator list", () => {
+      const spec = { aggregates: [], groupBy: [] };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        expect(e.kind).toBe("aggregate");
+      }
+    });
+    test("rejects undeclared aggregate op", () => {
+      const spec = { aggregates: [{ fn: "sum", alias: "total", field: "age" }], groupBy: [] };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures[0].alias).toBe("total");
+        expect(err.failures[0].cause).toContain("Undeclared");
+      }
+    });
+    test("rejects duplicate aliases", () => {
+      const spec = {
+        aggregates: [
+          { fn: "count", alias: "total" },
+          { fn: "count", alias: "total" }
+        ],
+        groupBy: []
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.failures.some((f) => f.alias === "total")).toBe(true);
+      }
+    });
+    test("validates where filter against schema", () => {
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: [],
+        where: FilterGroup.create().eq("unknownField", 42)
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+    });
+    test("collects multiple failures", () => {
+      const spec = {
+        aggregates: [
+          { fn: "sum", alias: "x", field: "age" },
+          { fn: "avg", alias: "x", field: "age" }
+        ],
+        groupBy: []
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.failures.length).toBeGreaterThanOrEqual(2);
+      }
+    });
+    test("rejects unknown groupBy field", () => {
+      const allOps = { aggregateOps: ["count", "sum"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["nonexistent"]
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, allOps, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures[0].cause).toContain("groupBy");
+        expect(err.failures[0].field).toBe("nonexistent");
+      }
+    });
+    test("rejects alias colliding with groupBy field name", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "name" }],
+        groupBy: ["name"]
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, allOps, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures.some((f) => String(f.cause).includes("collides"))).toBe(true);
+      }
+    });
+    test("rejects unknown having field", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["name"],
+        having: FilterGroup.create().gt("nonexistent", 0)
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, allOps, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures[0].cause).toContain("having");
+      }
+    });
+    test("having accepts alias and groupBy field names", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["name"],
+        having: FilterGroup.create().gt("total", 0).eq("name", "Alice")
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, allOps, spec)).not.toThrow();
+    });
+    test("passes valid groupBy with known schema fields", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["name", "age"]
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, allOps, spec)).not.toThrow();
+    });
+  });
+}
+
+// src/orm/orm-adapter.ts
+var OrmAdapter = class {
+  queryableOps = [];
+  updateOps = [];
+  aggregateOps = [];
+  supportedFieldTypes = [];
+  onFatalError(err) {
+    const wrapped = err instanceof EquippedError ? err : new EquippedError("OrmAdapter fatal error", {}, err);
+    Instance.crash(wrapped);
+  }
+  constructor() {
+    const self = this;
+    if (typeof self.connect === "function") {
+      Instance.on("start", () => self.connect(), { class: this.constructor });
+    }
+    if (typeof self.disconnect === "function") {
+      Instance.on("close", () => self.disconnect(), { class: this.constructor });
+    }
+  }
+  use(schema, config) {
+    const self = this;
+    const emptyIterator = async function* () {
+    };
+    const use = {
+      findMany: (filter, opts) => self.findMany?.(schema, config, filter, opts) ?? Promise.resolve([]),
+      iterateMany: (filter, opts) => self.iterateMany?.(schema, config, filter, opts) ?? emptyIterator(),
+      findOne: async (filter) => {
+        const rows = await use.findMany(filter, { limit: 1 });
+        return rows[0] ?? null;
+      },
+      count: (filter) => self.count?.(schema, config, filter) ?? Promise.reject(new Error("count not implemented")),
+      createOne: async (d) => {
+        const rows = await use.createMany([d]);
+        return rows[0];
+      },
+      createMany: (d) => self.createMany?.(schema, config, d) ?? Promise.resolve([]),
+      updateMany: (filter, d) => self.updateMany?.(schema, config, filter, d) ?? Promise.resolve([]),
+      updateOne: async (filter, d) => {
+        const match = await use.findOne(filter);
+        if (!match) return null;
+        const pk = schema.pkField.name;
+        const pkFilter = FilterGroup.create().eq(pk, match[pk]);
+        const rows = await use.updateMany(pkFilter, d);
+        return rows[0] ?? null;
+      },
+      upsertOne: (filter, create, ops) => self.upsertOne?.(schema, config, filter, create, ops) ?? Promise.reject(new Error("upsertOne not implemented")),
+      deleteOne: async (filter) => {
+        const row = await use.findOne(filter);
+        if (!row) return null;
+        const pk = schema.pkField.name;
+        if (self.deleteByPk) {
+          await self.deleteByPk(schema, config, row[pk]);
+        } else if (self.deleteMany) {
+          const pkFilter = FilterGroup.create().eq(pk, row[pk]);
+          await self.deleteMany(schema, config, pkFilter);
+        }
+        return row;
+      },
+      deleteMany: (filter) => self.deleteMany?.(schema, config, filter) ?? Promise.resolve([]),
+      raw: (...args) => self.raw?.(schema, config, ...args) ?? Promise.reject(new Error("raw not implemented")),
+      aggregate: (spec) => self.aggregate?.(schema, config, spec) ?? Promise.reject(new Error("aggregate not implemented")),
+      aggregateOps: self.aggregateOps ?? []
+    };
+    return use;
+  }
+};
+if (void 0) {
+  const { describe, test, expect, vi } = void 0;
+  const { v: v2 } = await null;
+  describe("OrmAdapter", () => {
+    test("subclass with connect/disconnect auto-registers Instance hooks", async () => {
+      const { Instance: Inst } = await null;
+      const onSpy = vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class TestAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        supportedFieldTypes = ["string"];
+        async connect() {
+        }
+        async disconnect() {
+        }
+      }
+      new TestAdapter();
+      expect(onSpy).toHaveBeenCalledWith("start", expect.any(Function), expect.objectContaining({ class: TestAdapter }));
+      expect(onSpy).toHaveBeenCalledWith("close", expect.any(Function), expect.objectContaining({ class: TestAdapter }));
+      onSpy.mockRestore();
+    });
+    test("subclass without connect/disconnect does not register hooks", async () => {
+      const { Instance: Inst } = await null;
+      const onSpy = vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class MinimalAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+      }
+      new MinimalAdapter();
+      expect(onSpy).not.toHaveBeenCalled();
+      onSpy.mockRestore();
+    });
+    test("capability declarations default to empty arrays", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class DefaultAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+      }
+      const adapter = new DefaultAdapter();
+      expect(adapter.queryableOps).toEqual([]);
+      expect(adapter.updateOps).toEqual([]);
+      expect(adapter.aggregateOps).toEqual([]);
+      expect(adapter.supportedFieldTypes).toEqual([]);
+      vi.restoreAllMocks();
+    });
+    test("onFatalError wraps non-EquippedError and calls Instance.crash", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      const crashSpy = vi.spyOn(Inst, "crash").mockImplementation((() => {
+        throw new Error("crash");
+      }));
+      class FatalAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        triggerFatal() {
+          this.onFatalError(new Error("something broke"));
+        }
+      }
+      const adapter = new FatalAdapter();
+      expect(() => adapter.triggerFatal()).toThrow("crash");
+      expect(crashSpy).toHaveBeenCalled();
+      vi.restoreAllMocks();
+    });
+    test("onFatalError passes through EquippedError directly", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let crashedWith;
+      vi.spyOn(Inst, "crash").mockImplementation(((err) => {
+        crashedWith = err;
+        throw err;
+      }));
+      class FatalAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        triggerFatal() {
+          this.onFatalError(new EquippedError("equipped error", { detail: "test" }));
+        }
+      }
+      const adapter = new FatalAdapter();
+      expect(() => adapter.triggerFatal()).toThrow();
+      expect(crashedWith).toBeInstanceOf(EquippedError);
+      expect(crashedWith.message).toBe("equipped error");
+      vi.restoreAllMocks();
+    });
+    test("use() creates OrmUse bridge that delegates to flat methods", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class BridgeAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        supportedFieldTypes = ["string"];
+        queryableOps = ["eq"];
+        async findMany(_s, _c, _f, _o) {
+          return [{ id: "found" }];
+        }
+        async count(_s, _c, _f) {
+          return 1;
+        }
+        async *iterateMany(_s, _c, _f, _o) {
+          yield { id: "iterated" };
+        }
+        async createMany(_s, _c, data) {
+          return data;
+        }
+      }
+      const TestSchema = Schema.from("bridge_test").pk("id", v2.string(), () => "x").build();
+      const adapter = new BridgeAdapter();
+      const ormUse = adapter.use(TestSchema, { table: "bridge_test" });
+      const rows = await ormUse.findMany(FilterGroup.create());
+      expect(rows).toEqual([{ id: "found" }]);
+      await expect(ormUse.count(FilterGroup.create())).resolves.toBe(1);
+      const iterated = [];
+      for await (const row of ormUse.iterateMany(FilterGroup.create())) iterated.push(row);
+      expect(iterated).toEqual([{ id: "iterated" }]);
+      const created = await ormUse.createOne({ id: "new" });
+      expect(created).toEqual({ id: "new" });
+      vi.restoreAllMocks();
+    });
+    test("use() bridge delegates updateMany to flat method", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class UpdateAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        supportedFieldTypes = ["string", "number"];
+        updateOps = ["set"];
+        async findMany(_s, _c, _f) {
+          return [{ id: "u1", name: "old" }];
+        }
+        async updateMany(_s, _c, _f, data) {
+          return [{ id: "u1", ...data }];
+        }
+      }
+      const TestSchema = Schema.from("upd_test").pk("id", v2.string(), () => "x").field("name", v2.string()).build();
+      const adapter = new UpdateAdapter();
+      const ormUse = adapter.use(TestSchema, { table: "upd_test" });
+      const updated = await ormUse.updateOne(FilterGroup.create().eq("id", "u1"), { name: "new" });
+      expect(updated).not.toBeNull();
+      expect(updated.name).toBe("new");
+      vi.restoreAllMocks();
+    });
+    test("use().iterateMany does not fall back to findMany when adapter omits iterateMany", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let findManyCalls = 0;
+      class FindOnlyAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        supportedFieldTypes = ["string"];
+        async findMany() {
+          findManyCalls += 1;
+          return [{ id: "found" }];
+        }
+      }
+      const TestSchema = Schema.from("iter_no_fallback").pk("id", v2.string(), () => "x").build();
+      const adapter = new FindOnlyAdapter();
+      const rows = [];
+      for await (const row of adapter.use(TestSchema, { table: "iter_no_fallback" }).iterateMany(FilterGroup.create())) rows.push(row);
+      expect(rows).toEqual([]);
+      expect(findManyCalls).toBe(0);
+      vi.restoreAllMocks();
+    });
+    test("use() bridge delegates deleteByPk via deleteOne", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let deletedPk = null;
+      class DeleteAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        supportedFieldTypes = ["string"];
+        async findMany(_s, _c, _f) {
+          return [{ id: "d1" }];
+        }
+        async deleteByPk(_s, _c, pk) {
+          deletedPk = pk;
+          return { id: String(pk) };
+        }
+      }
+      const TestSchema = Schema.from("del_test").pk("id", v2.string(), () => "x").build();
+      const adapter = new DeleteAdapter();
+      const ormUse = adapter.use(TestSchema, { table: "del_test" });
+      const deleted = await ormUse.deleteOne(FilterGroup.create().eq("id", "d1"));
+      expect(deleted).toEqual({ id: "d1" });
+      expect(deletedPk).toBe("d1");
+      vi.restoreAllMocks();
+    });
+    test("use() bridge delegates session to flat method", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let sessionRan = false;
+      class SessionAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        async session(fn) {
+          sessionRan = true;
+          return fn();
+        }
+      }
+      const adapter = new SessionAdapter();
+      const result = await adapter.session(async () => 42);
+      expect(result).toBe(42);
+      expect(sessionRan).toBe(true);
+      vi.restoreAllMocks();
+    });
+    test("type-level: subclass method override enforces canonical signature", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class CorrectAdapter extends OrmAdapter {
+        schemaConfigPipe = v2.object({ table: v2.string() });
+        async findByPk(_s, _c, _pk) {
+          return null;
+        }
+        async createMany(_s, _c, _d) {
+          return [];
+        }
+        async raw(_s, _c, ..._args) {
+          return null;
+        }
+      }
+      const adapter = new CorrectAdapter();
+      expect(adapter.findByPk).toBeTypeOf("function");
+      expect(adapter.createMany).toBeTypeOf("function");
+      expect(adapter.raw).toBeTypeOf("function");
+      vi.restoreAllMocks();
+    });
+  });
+}
+
+// src/orm/updates.ts
+var SetOp = class {
+  constructor(values) {
+    this.values = values;
+  }
+  kind = "set";
+};
+var IncOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "inc";
+};
+var MulOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "mul";
+};
+var MinOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "min";
+};
+var MaxOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "max";
+};
+var UnsetOp = class {
+  constructor(field) {
+    this.field = field;
+  }
+  kind = "unset";
+};
+var PushOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "push";
+};
+var PullOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "pull";
+};
+var PatchOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "patch";
+};
+function isUpdateOp(v2) {
+  return v2 instanceof SetOp || v2 instanceof IncOp || v2 instanceof MulOp || v2 instanceof MinOp || v2 instanceof MaxOp || v2 instanceof UnsetOp || v2 instanceof PushOp || v2 instanceof PullOp || v2 instanceof PatchOp;
+}
+function set(values) {
+  return new SetOp(values);
+}
+function inc(field, value) {
+  return new IncOp(toFieldName(field), value);
+}
+function mul(field, value) {
+  return new MulOp(toFieldName(field), value);
+}
+function min(field, value) {
+  return new MinOp(toFieldName(field), value);
+}
+function max(field, value) {
+  return new MaxOp(toFieldName(field), value);
+}
+function unset(field) {
+  return new UnsetOp(toFieldName(field));
+}
+function push(field, value) {
+  return new PushOp(toFieldName(field), value);
+}
+function pull(field, value) {
+  return new PullOp(toFieldName(field), value);
+}
+function patch(field, value) {
+  return new PatchOp(toFieldName(field), value);
+}
+function opTouchedFields(op) {
+  if (op instanceof SetOp) return Object.keys(op.values);
+  return [op.field];
+}
+function flattenOps(ops) {
+  const data = {};
+  for (const op of ops) {
+    if (op instanceof SetOp) Object.assign(data, op.values);
+    else data[op.field] = op;
+  }
+  return data;
+}
+if (void 0) {
+  const { describe, test, expect, expectTypeOf } = void 0;
+  const { v: v2 } = await null;
+  const { Schema } = await null;
+  const TestSchema = Schema.from("test").pk("id", v2.string(), () => "x").field("name", v2.string()).field("age", v2.number()).field("score", v2.optional(v2.number())).field("tags", v2.array(v2.string())).field("meta", v2.object({ a: v2.number() })).field("createdAt", v2.number(), { onCreate: () => 1e3 }).field("updatedAt", v2.number(), { onCreate: () => 1e3, onUpdate: () => 2e3 }).build();
+  describe("op classes", () => {
+    test('SetOp has kind "set" and stores values', () => {
+      const op = new SetOp({ name: "Alice" });
+      expect(op.kind).toBe("set");
+      expect(op.values).toEqual({ name: "Alice" });
+    });
+    test('IncOp has kind "inc" and stores field + value', () => {
+      const op = new IncOp("age", 5);
+      expect(op.kind).toBe("inc");
+      expect(op.field).toBe("age");
+      expect(op.value).toBe(5);
+    });
+    test('MulOp has kind "mul" and stores field + value', () => {
+      const op = new MulOp("score", 3);
+      expect(op.kind).toBe("mul");
+      expect(op.field).toBe("score");
+      expect(op.value).toBe(3);
+    });
+    test('MinOp has kind "min"', () => {
+      expect(new MinOp("age", 10).kind).toBe("min");
+    });
+    test('MaxOp has kind "max"', () => {
+      expect(new MaxOp("age", 99).kind).toBe("max");
+    });
+    test('UnsetOp has kind "unset"', () => {
+      expect(new UnsetOp("score").kind).toBe("unset");
+    });
+    test('PushOp has kind "push"', () => {
+      expect(new PushOp("tags", "x").kind).toBe("push");
+    });
+    test('PullOp has kind "pull"', () => {
+      expect(new PullOp("tags", "x").kind).toBe("pull");
+    });
+    test('PatchOp has kind "patch"', () => {
+      expect(new PatchOp("meta", { a: 9 }).kind).toBe("patch");
+    });
+  });
+  describe("isUpdateOp", () => {
+    test("returns true for every op class", () => {
+      expect(isUpdateOp(new SetOp({}))).toBe(true);
+      expect(isUpdateOp(new IncOp("f", 1))).toBe(true);
+      expect(isUpdateOp(new MulOp("f", 2))).toBe(true);
+      expect(isUpdateOp(new MinOp("f", 0))).toBe(true);
+      expect(isUpdateOp(new MaxOp("f", 10))).toBe(true);
+      expect(isUpdateOp(new UnsetOp("f"))).toBe(true);
+      expect(isUpdateOp(new PushOp("f", "v"))).toBe(true);
+      expect(isUpdateOp(new PullOp("f", "v"))).toBe(true);
+      expect(isUpdateOp(new PatchOp("f", {}))).toBe(true);
+    });
+    test("returns false for non-op values", () => {
+      expect(isUpdateOp("string")).toBe(false);
+      expect(isUpdateOp(42)).toBe(false);
+      expect(isUpdateOp(null)).toBe(false);
+      expect(isUpdateOp({})).toBe(false);
+    });
+  });
+  describe("op helper functions", () => {
+    test("set() creates SetOp with values", () => {
+      const op = set({ name: "Alice", age: 30 });
+      expect(op).toBeInstanceOf(SetOp);
+      expect(op.kind).toBe("set");
+      expect(op.values).toEqual({ name: "Alice", age: 30 });
+    });
+    test("inc() creates IncOp from field ref", () => {
+      const op = inc(TestSchema.fields.age, 5);
+      expect(op).toBeInstanceOf(IncOp);
+      expect(op.field).toBe("age");
+      expect(op.value).toBe(5);
+    });
+    test("mul() creates MulOp from field ref", () => {
+      const op = mul(TestSchema.fields.age, 3);
+      expect(op).toBeInstanceOf(MulOp);
+      expect(op.field).toBe("age");
+      expect(op.value).toBe(3);
+    });
+    test("min() creates MinOp from field ref", () => {
+      const op = min(TestSchema.fields.age, 10);
+      expect(op).toBeInstanceOf(MinOp);
+      expect(op.field).toBe("age");
+    });
+    test("max() creates MaxOp from field ref", () => {
+      const op = max(TestSchema.fields.age, 99);
+      expect(op).toBeInstanceOf(MaxOp);
+      expect(op.field).toBe("age");
+    });
+    test("unset() creates UnsetOp from field ref", () => {
+      const op = unset(TestSchema.fields.score);
+      expect(op).toBeInstanceOf(UnsetOp);
+      expect(op.field).toBe("score");
+    });
+    test("push() creates PushOp from field ref", () => {
+      const op = push(TestSchema.fields.tags, "new-tag");
+      expect(op).toBeInstanceOf(PushOp);
+      expect(op.field).toBe("tags");
+      expect(op.value).toBe("new-tag");
+    });
+    test("pull() creates PullOp from field ref", () => {
+      const op = pull(TestSchema.fields.tags, "old-tag");
+      expect(op).toBeInstanceOf(PullOp);
+      expect(op.field).toBe("tags");
+    });
+    test("patch() creates PatchOp from field ref", () => {
+      const op = patch(TestSchema.fields.meta, { a: 9 });
+      expect(op).toBeInstanceOf(PatchOp);
+      expect(op.field).toBe("meta");
+      expect(op.value).toEqual({ a: 9 });
+    });
+  });
+  describe("opTouchedFields", () => {
+    test("SetOp returns all keys from values", () => {
+      expect(opTouchedFields(new SetOp({ name: "A", age: 1 }))).toEqual(["name", "age"]);
+    });
+    test("IncOp returns the field", () => {
+      expect(opTouchedFields(new IncOp("age", 1))).toEqual(["age"]);
+    });
+    test("UnsetOp returns the field", () => {
+      expect(opTouchedFields(new UnsetOp("score"))).toEqual(["score"]);
+    });
+  });
+  describe("type-level: field-category helpers", () => {
+    test("NumericFieldOf only matches numeric fields (excludes optional numeric)", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("ComparableFieldOf matches numeric and string fields (excludes optional)", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("OptionalFieldOf only matches optional fields", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("ArrayFieldOf only matches array fields", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("ObjectFieldOf only matches object fields (not arrays)", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("type-level: inc on a string field is a TS error", () => {
+    test("inc rejects non-numeric fields", () => {
+      inc(TestSchema.fields.name, 1);
+    });
+  });
+  describe("type-level: push on a non-array field is a TS error", () => {
+    test("push rejects non-array fields", () => {
+      push(TestSchema.fields.name, "val");
+    });
+  });
+  describe("type-level: per-op gating via UpdateOp<S, A>", () => {
+    test("undeclared ops resolve to never", async () => {
+      const { OrmAdapter: OrmAdapter2 } = await null;
+      class LimitedAdapter extends OrmAdapter2 {
+        schemaConfigPipe = v2.object({});
+        supportedFieldTypes = ["string", "number"];
+        updateOps = ["set", "inc"];
+      }
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("adapter with no updateOps resolves all variants to never", async () => {
+      const { OrmAdapter: OrmAdapter2 } = await null;
+      class NoOpsAdapter extends OrmAdapter2 {
+        schemaConfigPipe = v2.object({});
+        supportedFieldTypes = ["string"];
+        updateOps = [];
+      }
+      expectTypeOf().toBeNever();
+    });
+    test("adapter with all updateOps includes all variants", async () => {
+      const { OrmAdapter: OrmAdapter2 } = await null;
+      class FullAdapter extends OrmAdapter2 {
+        schemaConfigPipe = v2.object({});
+        supportedFieldTypes = ["string", "number"];
+        updateOps = ["set", "inc", "mul", "min", "max", "unset", "push", "pull", "patch"];
+      }
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+}
+
+export {
+  OrmValidationError,
+  Field,
+  toFieldName,
+  SchemaField,
+  ComputedField,
+  Filter,
+  FilterGroup,
+  assertNormalisedAggregate,
+  assertNormalisedFilter,
+  OrmAdapter,
+  SetOp,
+  IncOp,
+  MulOp,
+  MinOp,
+  MaxOp,
+  UnsetOp,
+  PushOp,
+  PullOp,
+  PatchOp,
+  isUpdateOp,
+  set,
+  inc,
+  mul,
+  min,
+  max,
+  unset,
+  push,
+  pull,
+  patch,
+  opTouchedFields,
+  flattenOps
+};
+//# sourceMappingURL=chunk-TWKHVLLT.mjs.map