joist-core 2.2.0-next.9 → 2.3.0

package/build/scopes.d.ts

@@ -0,0 +1,185 @@
+import { type Alias } from "./Aliases";
+import type { Entity } from "./Entity";
+import type { ExpressionCondition, ExpressionFilter, FilterAndSettings, FilterWithAlias, FindFilter } from "./EntityFilter";
+import type { GraphQLFilterWithAlias } from "./EntityGraphQLFilter";
+import type { EntityManager, FindFilterOptions } from "./EntityManager";
+import type { Loaded, LoadHint } from "./loadHints";
+import type { OrderOf } from "./typeMap";
+/**
+ * A scope fragment that introduces its own join aliases: a join tree plus conditions
+ * that reference the aliases it binds.
+ *
+ * Lets a scope express predicates a plain nested filter can't, e.g. a top-level `OR`
+ * spanning two different joined tables. Both halves are required — the `where` tree binds
+ * the aliases (via `as:`) that `conditions` reference, so neither is meaningful alone.
+ */
+export interface ScopeJoinFilter<T extends Entity> {
+    where: FilterWithAlias<T>;
+    conditions: ExpressionFilter;
+}
+/** A predicate expressed against a bound alias, i.e. `(a) => a.age.gte(18)`. */
+export type AliasFn<T extends Entity> = (a: Alias<T>) => ExpressionCondition | ExpressionCondition[] | ScopeJoinFilter<T>;
+/**
+ * Discriminates an {@link AliasFn} result that is a {@link ScopeJoinFilter} from a bare
+ * condition / condition array.
+ *
+ * A `ScopeJoinFilter` is the only `AliasFn` return that carries both `where` and `conditions`
+ * keys; `ExpressionFilter` (`and`/`or`), `ColumnCondition`/`RawCondition` (`kind`), and arrays
+ * have neither, so the two-key check is unambiguous.
+ */
+export declare function isScopeJoinFilter<T extends Entity>(result: ExpressionCondition | ExpressionCondition[] | ScopeJoinFilter<T>): result is ScopeJoinFilter<T>;
+/**
+ * The fluent builder to either a) terminate/invoke or b) chain scope methods.
+ *
+ * I.e. `Author.adult` is a ScopeQuery that can either do `.find` or `.popular`.
+ *
+ * This `ScopeQuery` is just the terminal/invocation methods, the `.popular` methods
+ * are chained on via the `Scope` mapped type below.
+ */
+export interface ScopeQuery<T extends Entity> {
+    /**
+     * ANDs an ad-hoc filter onto the scope, i.e. `Author.adult.where({ firstName: "a1" })`.
+     *
+     * Accepts either a plain find filter (`{ field: value }`) or an alias callback
+     * (`(a) => a.field.eq(value)`) and appends it to the recorded ops — multiple
+     * `.where(...)` calls on the same field AND together rather than override.
+     */
+    where(where: FilterWithAlias<T>): this;
+    where(fn: AliasFn<T>): this;
+    /**
+     * Appends an `orderBy` to the scope, i.e. `Author.adult.orderBy({ age: "DESC" })`.
+     *
+     * Chained `.orderBy(...)` calls **accumulate** (the resulting query has every recorded
+     * orderBy in declaration order), unlike `.limit`/`.offset`/`.softDeletes` which are
+     * last-wins. To replace an existing scope's ordering, pass `orderBy` to the terminal
+     * `.find(em, { orderBy: ... })` instead — terminal options override the scope's.
+     */
+    orderBy(orderBy: OrderOf<T> | OrderOf<T>[]): this;
+    /**
+     * Sets the row limit on the scope, i.e. `Author.adult.limit(10)`.
+     *
+     * Chained `.limit(...)` calls are last-wins — only the most recent value survives compile.
+     */
+    limit(limit: number): this;
+    /**
+     * Sets the row offset on the scope, i.e. `Author.adult.offset(10)`.
+     *
+     * Chained `.offset(...)` calls are last-wins — only the most recent value survives compile.
+     */
+    offset(offset: number): this;
+    /**
+     * Overrides Joist's default soft-delete handling for this query, i.e.
+     * `Author.adult.softDeletes("include")` to see soft-deleted rows.
+     *
+     * Chained `.softDeletes(...)` calls are last-wins. The effective value also gates
+     * how `.where({ relation: ... })` filters that touch soft-delete-aware entities are
+     * composed at compile time.
+     */
+    softDeletes(softDeletes: "include" | "exclude"): this;
+    /**
+     * Runs the scope against `em`, returning all matching rows.
+     *
+     * Terminal options (`orderBy`, `limit`, `offset`, `softDeletes`) passed here
+     * **override** anything the scope recorded via `.orderBy(...)`, `.limit(...)`, etc.;
+     * `conditions` passed here are ANDed with the scope's compiled conditions rather than
+     * replacing them. To extend the scope's ordering instead of replacing it, chain
+     * `.orderBy(...)` before `.find(em)`.
+     */
+    find(em: EntityManager): Promise<T[]>;
+    find<const H extends LoadHint<T>>(em: EntityManager, opts?: FindFilterOptions<T> & {
+        populate?: H;
+    }): Promise<Loaded<T, H>[]>;
+    /** Like {@link find} but returns a single match or `undefined`. Same options precedence as `find`. */
+    findOne(em: EntityManager): Promise<T | undefined>;
+    findOne<const H extends LoadHint<T>>(em: EntityManager, opts?: FindFilterOptions<T> & {
+        populate?: H;
+    }): Promise<Loaded<T, H> | undefined>;
+    /** Like {@link findOne} but throws if no row matches. Same options precedence as `find`. */
+    findOneOrFail(em: EntityManager): Promise<T>;
+    findOneOrFail<const H extends LoadHint<T>>(em: EntityManager, opts?: FindFilterOptions<T> & {
+        populate?: H;
+    }): Promise<Loaded<T, H>>;
+    /**
+     * Returns the count of rows matching the scope.
+     *
+     * Recorded `orderBy`/`limit`/`offset` ops are dropped (they're meaningless for a count);
+     * `softDeletes` and conditions still apply.
+     */
+    findCount(em: EntityManager): Promise<number>;
+    /**
+     * Returns the tagged ids of rows matching the scope.
+     *
+     * Like {@link findCount}, recorded `orderBy`/`limit`/`offset` ops are dropped.
+     */
+    findIds(em: EntityManager): Promise<string[]>;
+    /**
+     * Compiles the scope into Joist's `FilterAndSettings` shape for passing to other APIs
+     * or for inspection in tests.
+     *
+     * Useful primarily for debugging — the returned shape captures whatever the terminal
+     * `find` methods would have sent to `em.find`, before terminal-options precedence is
+     * applied.
+     */
+    toFindArgs(): FilterAndSettings<T>;
+}
+/** A scope for entity `T`, with chainable named accessors supplied by `S`. */
+export type Scope<T extends Entity, S = {}> = ScopeQuery<T> & S;
+/**
+ * A per-entity, pre-typed function for declaring scopes.
+ *
+ * I.e. this is the type of the `import { authorScope as scope }` that entity files
+ * use to declare their scopes.
+ *
+ * Because of the `authorScope as scope` rename, we can bake into the API that this
+ * is the Author entity, and so simplify its usage.
+ */
+export interface ScopeFn<T extends Entity, R extends Scope<T>> {
+    /** Defines a scope based on a filter condition, i.e. `scope({ name: "John" })` or `scope(a => a.name.eq("John")`. */
+    (arg: FilterWithAlias<T> | AliasFn<T>): R;
+    /** Defines a parametrized filter, i.e. `scope(name => ({ name: { startsWith: name } }))`. */
+    fn<A extends unknown[]>(fn: (...args: A) => FilterWithAlias<T> | AliasFn<T>): (...args: A) => R;
+}
+/** A scope fragment that can be expanded against any current query alias. */
+export type ScopeFilterFragment<T extends Entity> = {
+    kind: "alias";
+    fn: AliasFn<T>;
+} | {
+    kind: "filter";
+    filter: FilterWithAlias<T>;
+};
+/**
+ * Fully-expanded scope contents, with named refs resolved and settings collapsed.
+ *
+ * Deliberately *not* a `ParsedFindQuery`, even though they look adjacent: this is the pre-parse,
+ * alias-free *input* we feed into `parseFindQuery`, not its alias-committed AST output. Two reasons
+ * the distinction matters:
+ * - `fragments` are un-parsed DSL — filter objects plus un-invoked `AliasFn` closures — so the same
+ *   scope can be re-rooted onto the query's primary alias (`Author.adult.find(em)`) or onto a joined
+ *   relation alias (`em.find(Book, { author: Author.adult })`). A `ParsedFindQuery` has already baked
+ *   in concrete aliases like `a`/`b1` and could only be reused via alias-rewrite surgery.
+ * - keeping `fragments` as a *list* (rather than one merged condition tree) preserves independent-EXISTS
+ *   semantics: `.where({ books: ... }).where({ books: ... })` must stay two predicates — one EXISTS each —
+ *   which a collapsed `ParsedFindQuery.condition` can no longer be split back into.
+ */
+export interface ResolvedScope<T extends Entity> {
+    fragments: ScopeFilterFragment<T>[];
+    orderBys: OrderOf<T>[];
+    limit: number | undefined;
+    offset: number | undefined;
+    softDeletes: "include" | "exclude" | undefined;
+}
+/** Creates a per-entity, pre-typed scope function. */
+export declare function newScopeFn<T extends Entity, R extends Scope<T>>(entityType: string): ScopeFn<T, R>;
+/** Returns true if `value` is one of our scope proxies. */
+export declare function isScope<T extends Entity>(value: unknown): value is Scope<T>;
+/** Resolves a scope proxy into ordered filter fragments plus collapsed settings. */
+export declare function resolveScope<T extends Entity>(scope: Scope<T>): ResolvedScope<T>;
+/**
+ * Returns true for find filters that select every row of the entity type, i.e. an empty `{}` filter
+ * or a scope that resolved to no fragments.
+ *
+ * Used by `em.findCount` and the count dataloader to short-circuit in-memory delete adjustments, which
+ * are only safe when the query has no `where`/`conditions` to evaluate created/deleted entities against.
+ */
+export declare function isSelectAllFilter<T extends Entity>(where: FindFilter<T> | GraphQLFilterWithAlias<T>, conditions: ExpressionFilter | undefined): boolean;
+//# sourceMappingURL=scopes.d.ts.map

package/build/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"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"}

package/build/scopes.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isScopeJoinFilter = isScopeJoinFilter;
+exports.newScopeFn = newScopeFn;
+exports.isScope = isScope;
+exports.resolveScope = resolveScope;
+exports.isSelectAllFilter = isSelectAllFilter;
+const configure_1 = require("./configure");
+/**
+ * Discriminates an {@link AliasFn} result that is a {@link ScopeJoinFilter} from a bare
+ * condition / condition array.
+ *
+ * A `ScopeJoinFilter` is the only `AliasFn` return that carries both `where` and `conditions`
+ * keys; `ExpressionFilter` (`and`/`or`), `ColumnCondition`/`RawCondition` (`kind`), and arrays
+ * have neither, so the two-key check is unambiguous.
+ */
+function isScopeJoinFilter(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        !Array.isArray(result) &&
+        "where" in result &&
+        "conditions" in result);
+}
+// Use a symbol so stored scope fragments cannot collide with user-defined scope names.
+const kOps = Symbol("scopeOps");
+const kResolver = Symbol("scopeResolver");
+const kWithScopeOp = Symbol("scopeWithOp");
+// Symbol-keyed so it can't collide with a user's named scope (e.g. `Author.resolve`), which the
+// proxy would otherwise treat as a chained ref.
+const kResolve = Symbol("scopeResolve");
+/** Creates a per-entity, pre-typed scope function. */
+function newScopeFn(entityType) {
+    // We won't immediately have access to the EntityMetadata during static field assignment, so provide a lazy handle
+    const resolver = {
+        entityType,
+        maybeGet: () => (0, configure_1.maybeGetMetadataForType)(entityType)?.cstr,
+    };
+    // Create the scopeFn
+    function scopeFn(arg) {
+        return newScope(resolver, [toOp(arg)]);
+    }
+    // But then also add the `.fn(...)` for parameterized scopes
+    scopeFn.fn = function scopeFn(fn) {
+        return (...args) => newScope(resolver, [toOp(fn(...args))]);
+    };
+    return scopeFn;
+}
+/** Returns true if `value` is one of our scope proxies. */
+function isScope(value) {
+    // A scope is a callable Proxy (so parameterized refs like `Author.adult.named("a")` work), so it's
+    // always `typeof === "function"`; that guard also keeps the `in` checks from throwing on primitives.
+    return typeof value === "function" && kOps in value && kResolver in value;
+}
+/** Resolves a scope proxy into ordered filter fragments plus collapsed settings. */
+function resolveScope(scope) {
+    return asScopeInternalApi(scope)[kResolve]();
+}
+/**
+ * Returns true for find filters that select every row of the entity type, i.e. an empty `{}` filter
+ * or a scope that resolved to no fragments.
+ *
+ * Used by `em.findCount` and the count dataloader to short-circuit in-memory delete adjustments, which
+ * are only safe when the query has no `where`/`conditions` to evaluate created/deleted entities against.
+ */
+function isSelectAllFilter(where, conditions) {
+    if (conditions !== undefined)
+        return false;
+    if (isScope(where))
+        return resolveScope(where).fragments.length === 0;
+    return Object.keys(where).length === 0;
+}
+/**
+ * Creates an immutable scope proxy with `ops` as its current scope fragments.
+ *
+ * The proxy target is a function so the proxy is callable (for parameterized refs
+ * like `Author.adult.named("a")`); unknown property accesses always record a `ref`
+ * op, with validation against the entity constructor deferred until `compile` runs.
+ */
+function newScope(resolver, ops) {
+    const terminals = new ScopeTerminals(resolver, ops);
+    function callable() { }
+    Object.defineProperty(callable, kOps, { value: ops });
+    Object.defineProperty(callable, kResolver, { value: resolver });
+    return new Proxy(callable, {
+        get(target, prop) {
+            if (prop === kOps || prop === kResolver)
+                return Reflect.get(target, prop);
+            if (typeof prop === "symbol" || prop in terminals) {
+                const value = Reflect.get(terminals, prop, terminals);
+                return typeof value === "function" ? value.bind(terminals) : value;
+            }
+            // `await scope` probes `.then`; returning undefined lets await resolve to the scope itself
+            // instead of treating the proxy as a thenable.
+            if (prop === "then")
+                return undefined;
+            return newScope(resolver, [...ops, { kind: "ref", name: prop }]);
+        },
+        apply(_target, _thisArg, args) {
+            // Invoked for chained parameterized refs, i.e. the `("a")` in `Author.adult.named("a")`.
+            const lastOp = ops[ops.length - 1];
+            if (lastOp?.kind !== "ref")
+                throw new Error(`Scope is not parameterized`);
+            return newScope(resolver, [...ops.slice(0, -1), { ...lastOp, args }]);
+        },
+    });
+}
+/**
+ * Concrete builder/terminal methods for a scope proxy.
+ *
+ * The outer proxy handles dynamic named-scope access like `.popular`; this class handles
+ * fixed methods like `.where`, `.find`, and `.toFindArgs`.
+ */
+class ScopeTerminals {
+    #ops;
+    #resolver;
+    constructor(resolver, ops) {
+        this.#resolver = resolver;
+        this.#ops = ops;
+    }
+    get [kOps]() {
+        return this.#ops;
+    }
+    /** Flattens our recorded ops (resolving named refs, collapsing settings) into a {@link ResolvedScope}. */
+    [kResolve]() {
+        return resolveScopeOps(this.#resolver, this.#ops);
+    }
+    where(arg) {
+        return this[kWithScopeOp](toOp(arg));
+    }
+    orderBy(orderBy) {
+        return this[kWithScopeOp]({ kind: "orderBy", orderBy });
+    }
+    limit(limit) {
+        return this[kWithScopeOp]({ kind: "limit", limit });
+    }
+    offset(offset) {
+        return this[kWithScopeOp]({ kind: "offset", offset });
+    }
+    softDeletes(value) {
+        return this[kWithScopeOp]({ kind: "softDeletes", value });
+    }
+    toFindArgs() {
+        return compile(this.#resolver, this.#ops);
+    }
+    find(em, opts) {
+        const args = compile(this.#resolver, this.#ops);
+        return em.find(resolveCstr(this.#resolver), args.where, toFindOptions(args, opts));
+    }
+    findOne(em, opts) {
+        const args = compile(this.#resolver, this.#ops);
+        return em.findOne(resolveCstr(this.#resolver), args.where, toFindOptions(args, opts));
+    }
+    findOneOrFail(em, opts) {
+        const args = compile(this.#resolver, this.#ops);
+        return em.findOneOrFail(resolveCstr(this.#resolver), args.where, toFindOptions(args, opts));
+    }
+    findCount(em) {
+        const args = compile(this.#resolver, this.#ops);
+        return em.findCount(resolveCstr(this.#resolver), args.where, toCountOptions(args));
+    }
+    findIds(em) {
+        const args = compile(this.#resolver, this.#ops);
+        return em.findIds(resolveCstr(this.#resolver), args.where, toCountOptions(args));
+    }
+    /** Returns a new scope with one more recorded operation. */
+    [kWithScopeOp](op) {
+        return newScope(this.#resolver, [...this.#ops, op]);
+    }
+}
+/** Compiles the ordered scope ops into Joist's existing find args shape. */
+function compile(resolver, ops) {
+    const resolved = resolveScopeOps(resolver, ops);
+    return {
+        // A scope is a valid `FindFilter` `where`, so `em.find` re-parses & expands its fragments.
+        where: newScope(resolver, resolved.fragments),
+        orderBy: resolved.orderBys.length ? resolved.orderBys : undefined,
+        limit: resolved.limit,
+        offset: resolved.offset,
+        softDeletes: resolved.softDeletes,
+    };
+}
+/** Resolves ordered scope ops into filter fragments and root-only settings. */
+function resolveScopeOps(resolver, ops) {
+    const fragments = [];
+    const orderBys = [];
+    const refArgKeys = new WeakMap();
+    const nextRefArgKey = { value: 0 };
+    let limit;
+    let offset;
+    let softDeletes;
+    function expand(currentOps, seen) {
+        for (const op of currentOps) {
+            switch (op.kind) {
+                case "alias":
+                case "filter":
+                    fragments.push(op);
+                    break;
+                case "orderBy":
+                    if (Array.isArray(op.orderBy))
+                        orderBys.push(...op.orderBy);
+                    else
+                        orderBys.push(op.orderBy);
+                    break;
+                case "limit":
+                    limit = op.limit;
+                    break;
+                case "offset":
+                    offset = op.offset;
+                    break;
+                case "softDeletes":
+                    softDeletes = op.value;
+                    break;
+                case "ref": {
+                    const key = scopeRefKey(op, refArgKeys, nextRefArgKey);
+                    if (seen.has(key))
+                        break;
+                    seen.add(key);
+                    expand(scopeOpsForRef(resolver, op), seen);
+                    break;
+                }
+            }
+        }
+    }
+    expand(ops, new Set());
+    return { fragments, orderBys, limit, offset, softDeletes };
+}
+/** Resolves a recorded named-scope ref to its underlying ops. */
+function scopeOpsForRef(resolver, op) {
+    const cstr = resolveCstr(resolver);
+    const sibling = cstr[op.name];
+    if (op.args) {
+        // Scope proxies are also `typeof === "function"`, so explicitly reject them via `isScope`.
+        if (typeof sibling !== "function" || isScope(sibling)) {
+            throw new Error(`Scope ${resolver.entityType}.${op.name} is not parameterized`);
+        }
+        return scopeOpsFromValue(resolver, op.name, sibling(...op.args));
+    }
+    return scopeOpsFromValue(resolver, op.name, sibling);
+}
+/** Extracts recorded scope ops from a resolved static field. */
+function scopeOpsFromValue(resolver, name, value) {
+    if (isScope(value))
+        return asScopeInternalApi(value)[kOps];
+    if (value === undefined)
+        throw new Error(`Invalid scope ${resolver.entityType}.${name}`);
+    if (typeof value === "function")
+        throw new Error(`Scope ${resolver.entityType}.${name} requires arguments`);
+    throw new Error(`${resolver.entityType}.${name} is not a scope`);
+}
+/** Creates a cycle key for named-scope refs without serializing arbitrary entities/functions. */
+function scopeRefKey(op, refArgKeys, nextRefArgKey) {
+    return op.args
+        ? `${op.name}(${op.args.map((arg) => scopeRefArgKey(arg, refArgKeys, nextRefArgKey)).join(",")})`
+        : op.name;
+}
+/** Creates a stable per-resolution key for one named-scope argument. */
+function scopeRefArgKey(arg, refArgKeys, nextRefArgKey) {
+    if ((typeof arg === "object" && arg !== null) || typeof arg === "function") {
+        let key = refArgKeys.get(arg);
+        if (key === undefined) {
+            key = nextRefArgKey.value;
+            nextRefArgKey.value += 1;
+            refArgKeys.set(arg, key);
+        }
+        return `${typeof arg}:${key}`;
+    }
+    return `${typeof arg}:${JSON.stringify(String(arg))}`;
+}
+/** Narrows a known scope proxy to its internal-only (symbol-keyed) API. */
+function asScopeInternalApi(scope) {
+    if (!isScope(scope))
+        throw new Error("Invalid scope");
+    return scope;
+}
+/** Resolves the lazy entity constructor. */
+function resolveCstr(resolver) {
+    const cstr = resolver.maybeGet();
+    if (cstr === undefined)
+        throw new Error(`Unknown type ${resolver.entityType}`);
+    return cstr;
+}
+/** Converts a scope declaration argument into a recorded op. */
+function toOp(arg) {
+    return typeof arg === "function"
+        ? { kind: "alias", fn: arg }
+        : { kind: "filter", filter: arg };
+}
+/**
+ * Pulls the option half of `FilterAndSettings` back out for `em.find`.
+ *
+ * The scope's recorded settings are the defaults; terminal `opts` (orderBy/limit/offset/conditions/
+ * populate) override. The scope itself carries no `conditions` — it compiles to a `where` scope that
+ * `em.find` expands — so the only conditions are the caller's, which flow through the `...opts` spread.
+ */
+function toFindOptions(args, opts) {
+    return { orderBy: args.orderBy, limit: args.limit, offset: args.offset, softDeletes: args.softDeletes, ...opts };
+}
+/** Like `toFindOptions`, but drops the `orderBy`/`limit`/`offset` that `findCount`/`findIds` ignore. */
+function toCountOptions(args) {
+    return { softDeletes: args.softDeletes };
+}
+//# sourceMappingURL=scopes.js.map

package/build/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"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"}

package/build/temporal.d.ts

@@ -1,9 +1,39 @@
-import type { Intl, Temporal, toTemporalInstant } from "temporal-polyfill";
+import { type Intl, type Temporal as TemporalType, type toTemporalInstant } from "temporal-polyfill";
 type RequireTemporal = {
-    Temporal: typeof Temporal;
+    Temporal: typeof TemporalType;
     toTemporalInstant: typeof toTemporalInstant;
     Intl: typeof Intl;
 };
+/**
+ * Lazily exposes Joist's native-first / polyfill-fallback Temporal detection.
+ *
+ * This is useful while the joist-orm repo itself has both pre-Node 26, and post-Node 26
+ * test coverage, b/c our CI test suite needs the same a) codegen output and b) test suites
+ * to "just work" with either Node 24/25 or Node 26, which means they can't have an explicit
+ * import to either `temporal-polyfill` or the `Temporal` global.
+ *
+ * This is exactly what Joist's internal temporal resolution was already working around, so
+ * this just exposes an `import { Temporal } from joist-orm` that lets the codegen & tests
+ * reuse the same abstraction.
+ */
+export declare const Temporal: typeof TemporalType;
+/**
+ * A type-only `Temporal` namespace that merges with the `const Temporal` above.
+ *
+ * The `const` is only a value, so using `Temporal.PlainDate` / `Temporal.ZonedDateTime` as a
+ * type needs a namespace to resolve against. Node 26 has that as a global, but older Node
+ * versions don't, so we add it here by pointing the names at `temporal-polyfill`'s types.
+ */
+export declare namespace Temporal {
+    type Instant = TemporalType.Instant;
+    type ZonedDateTime = TemporalType.ZonedDateTime;
+    type PlainDate = TemporalType.PlainDate;
+    type PlainTime = TemporalType.PlainTime;
+    type PlainDateTime = TemporalType.PlainDateTime;
+    type PlainYearMonth = TemporalType.PlainYearMonth;
+    type PlainMonthDay = TemporalType.PlainMonthDay;
+    type Duration = TemporalType.Duration;
+}
 /**
  * Conditionally/dynamically requires `temporal-polyfill`.
  *

package/build/temporal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3E,KAAK,eAAe,GAAG;IAAE,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAAC,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAAC,IAAI,EAAE,OAAO,IAAI,CAAA;CAAE,CAAC;AAGrH;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,SAAS,CA2BlE;AAED,wBAAgB,eAAe,IAAI,eAAe,CAEjD"}
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,IAAI,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGrG,KAAK,eAAe,GAAG;IACrB,QAAQ,EAAE,OAAO,YAAY,CAAC;IAC9B,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,IAAI,EAAE,OAAO,IAAI,CAAC;CACnB,CAAC;AAGF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,EAOhB,OAAO,YAAY,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,KAAY,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC;IAC3C,KAAY,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC;IACvD,KAAY,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC;IAC/C,KAAY,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC;IAC/C,KAAY,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC;IACvD,KAAY,cAAc,GAAG,YAAY,CAAC,cAAc,CAAC;IACzD,KAAY,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC;IACvD,KAAY,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;CAC9C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,SAAS,CA2BlE;AAED,wBAAgB,eAAe,IAAI,eAAe,CAEjD"}

package/build/temporal.js

@@ -1,9 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Temporal = void 0;
 exports.maybeRequireTemporal = maybeRequireTemporal;
 exports.requireTemporal = requireTemporal;
 const utils_1 = require("./utils");
 let temporal;
+/**
+ * Lazily exposes Joist's native-first / polyfill-fallback Temporal detection.
+ *
+ * This is useful while the joist-orm repo itself has both pre-Node 26, and post-Node 26
+ * test coverage, b/c our CI test suite needs the same a) codegen output and b) test suites
+ * to "just work" with either Node 24/25 or Node 26, which means they can't have an explicit
+ * import to either `temporal-polyfill` or the `Temporal` global.
+ *
+ * This is exactly what Joist's internal temporal resolution was already working around, so
+ * this just exposes an `import { Temporal } from joist-orm` that lets the codegen & tests
+ * reuse the same abstraction.
+ */
+exports.Temporal = new Proxy({}, {
+    get(_target, property, receiver) {
+        return Reflect.get(requireTemporal().Temporal, property, receiver);
+    },
+});
 /**
  * Conditionally/dynamically requires `temporal-polyfill`.
  *

package/build/temporal.js.map

@@ -1 +1 @@
-{"version":3,"file":"temporal.js","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":";;AAYA,oDA2BC;AAED,0CAEC;AA1CD,mCAA+B;AAG/B,IAAI,QAA6C,CAAC;AAElD;;;;;GAKG;AACH,SAAgB,oBAAoB;IAClC,+EAA+E;IAC/E,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACzC,oDAAoD;IACpD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,mCAAmC;IACnC,IAAI,UAAU,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QAC7C,QAAQ,GAAG;YACT,QAAQ,EAAE,MAAM,CAAC,QAA2B;YAC5C,iBAAiB,EAAG,IAAI,CAAC,SAAiB,CAAC,iBAAiB;YAC5D,IAAI,EAAE,MAAM,CAAC,IAAmB;SACjC,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,8CAA8C;IAC9C,IAAI,CAAC;QACH,QAAQ,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACxC,OAAO,QAA2B,CAAC;IACrC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAA,CAAC;IACd,gDAAgD;IAChD,IAAI,CAAC;QACH,QAAQ,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;QAC5C,OAAO,QAA2B,CAAC;IACrC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAA,CAAC;IACd,mCAAmC;IACnC,QAAQ,GAAG,KAAK,CAAC;IACjB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAgB,eAAe;IAC7B,OAAO,oBAAoB,EAAE,IAAI,IAAA,YAAI,EAAC,0CAA0C,CAAC,CAAC;AACpF,CAAC"}
+{"version":3,"file":"temporal.js","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":";;;AAuDA,oDA2BC;AAED,0CAEC;AArFD,mCAA+B;AAO/B,IAAI,QAA6C,CAAC;AAElD;;;;;;;;;;;GAWG;AACU,QAAA,QAAQ,GAAG,IAAI,KAAK,CAC/B,EAAE,EACF;IACE,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ;QAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC;CACF,CACqB,CAAC;AAoBzB;;;;;GAKG;AACH,SAAgB,oBAAoB;IAClC,+EAA+E;IAC/E,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACzC,oDAAoD;IACpD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,mCAAmC;IACnC,IAAI,UAAU,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QAC7C,QAAQ,GAAG;YACT,QAAQ,EAAE,MAAM,CAAC,QAA2B;YAC5C,iBAAiB,EAAG,IAAI,CAAC,SAAiB,CAAC,iBAAiB;YAC5D,IAAI,EAAE,MAAM,CAAC,IAAmB;SACjC,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,8CAA8C;IAC9C,IAAI,CAAC;QACH,QAAQ,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACxC,OAAO,QAA2B,CAAC;IACrC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAA,CAAC;IACd,gDAAgD;IAChD,IAAI,CAAC;QACH,QAAQ,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;QAC5C,OAAO,QAA2B,CAAC;IACrC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAA,CAAC;IACd,mCAAmC;IACnC,QAAQ,GAAG,KAAK,CAAC;IACjB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAgB,eAAe;IAC7B,OAAO,oBAAoB,EAAE,IAAI,IAAA,YAAI,EAAC,0CAA0C,CAAC,CAAC;AACpF,CAAC"}

package/build/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../src/upsert.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAY,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,IAAI,EAAS,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAE7F,OAAO,EAIL,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAW,MAAM,SAAS,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI;IAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CAAE,GAAG,yCAAyC,CACnH,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CACvC,GACC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEd,8DAA8D;AAC9D,KAAK,eAAe,GAAG;IACrB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;CACtD,CAAC;AAEF,2CAA2C;AAC3C,KAAK,UAAU,GAAG;IAChB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,KAAK,yCAAyC,CAAC,CAAC,IAAI;KACjD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,CAAC,GACjD,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACtB,CAAC,SAAS,MAAM,GACd,KAAK,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GACpE,CAAC,CAAC,CAAC,CAAC,GACN,CAAC,SAAS,MAAM,GACd,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GACxD,CAAC,CAAC,CAAC,CAAC,GACR,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAmM3G;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,MAAM,EAC3C,EAAE,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAChC,WAAW,EAAE,8BAA8B,CAAC,CAAC,CAAC,EAC9C,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAcZ"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../src/upsert.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAY,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,IAAI,EAAS,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAE7F,OAAO,EAIL,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAW,MAAM,SAAS,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI;IAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CAAE,GAAG,yCAAyC,CACnH,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CACvC,GACC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEd,8DAA8D;AAC9D,KAAK,eAAe,GAAG;IACrB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;CACtD,CAAC;AAEF,2CAA2C;AAC3C,KAAK,UAAU,GAAG;IAChB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,KAAK,yCAAyC,CAAC,CAAC,IAAI;KACjD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,CAAC,GACjD,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACtB,CAAC,SAAS,MAAM,GACd,KAAK,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GACpE,CAAC,CAAC,CAAC,CAAC,GACN,CAAC,SAAS,MAAM,GACd,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GACxD,CAAC,CAAC,CAAC,CAAC,GACR,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAyM3G;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,MAAM,EAC3C,EAAE,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAChC,WAAW,EAAE,8BAA8B,CAAC,CAAC,CAAC,EAC9C,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAcZ"}

package/build/upsert.js

@@ -140,8 +140,10 @@ async function updatePartial(entity, input) {
             const values = (0, utils_1.toArray)(value);
             const otherMeta = field.otherMetadata();
             const maybeSoftDelete = otherMeta.timestampFields?.deletedAt;
-            // Incremental handling
-            const anyValueHasOp = values.some((v) => v && typeof v === "object" && !(0, Entity_1.isEntity)(v) && "op" in v);
+            // Incremental handling. Detect incremental mode by a meaningful `op` value--`op: undefined`/`op: null`
+            // is the natural shape of an optional field and must behave like "no op", consistent with how
+            // updatePartial treats `value === undefined` and how delete/remove are read by truthiness.
+            const anyValueHasOp = values.some((v) => v && typeof v === "object" && !(0, Entity_1.isEntity)(v) && v.op != null);
             if (anyValueHasOp) {
                 let anyValueMissingOp = false;
                 const current = entity[name];
@@ -171,6 +173,11 @@ async function updatePartial(entity, input) {
                     else if (op === "incremental") {
                         // This is a marker entry, just ignore it
                     }
+                    else {
+                        // A child entered incremental mode (a sibling had a real op) but has no op of its own;
+                        // never silently skip it--flag it so the guard below throws instead of dropping the row.
+                        anyValueMissingOp = true;
+                    }
                 }));
                 if (anyValueMissingOp) {
                     throw new Error("If any child sets the `op` key, then all children must have the `op` key.");