uql-orm 0.47.1 → 0.49.0

package/dist/type/entity.d.ts

@@ -182,9 +182,10 @@ export type UpdatePayload<E> = {
  */
 export type FieldValue<E> = E[FieldKey<E>];
 /**
- * Infers the name of the key identifier on an entity
+ * The key's name where the entity states it: the `idKey` brand first, then the conventional names.
+ * `never` when nothing does, which is the case {@link IdKey} falls back on and `@Id` refuses.
  */
-export type IdKey<E> = (E extends {
+export type NamedIdKey<E> = E extends {
     [idKey]?: infer K;
 } ? K & FieldKey<E> : E extends {
     _id?: unknown;
@@ -192,7 +193,11 @@ export type IdKey<E> = (E extends {
     id?: unknown;
 } ? 'id' & FieldKey<E> : E extends {
     uuid?: unknown;
-} ? 'uuid' & FieldKey<E> : FieldKey<E>) & string;
+} ? 'uuid' & FieldKey<E> : never;
+/**
+ * Infers the name of the key identifier on an entity
+ */
+export type IdKey<E> = ([NamedIdKey<E>] extends [never] ? FieldKey<E> : NamedIdKey<E>) & string;
 /**
  * Infers the value of the key identifier on an entity.
  *
@@ -570,7 +575,7 @@ export type RelationManyToManyOptions<E> = RelationOptionsThroughOwner<E> | Rela
 /**
  * Lifecycle hook event names.
  */
-export type HookEvent = 'beforeInsert' | 'afterInsert' | 'beforeUpdate' | 'afterUpdate' | 'beforeDelete' | 'afterDelete' | 'afterLoad';
+export type HookEvent = 'beforeInsert' | 'afterInsert' | 'beforeUpdate' | 'afterUpdate' | 'beforeUpsert' | 'afterUpsert' | 'beforeDelete' | 'afterDelete' | 'afterLoad';
 /**
  * A registered hook: the method name on the entity class to call.
  */

package/dist/type/queryRaw.d.ts

@@ -25,7 +25,7 @@ export type QueryRawFnOptions = {
 /**
  * A `raw` callback: write into `ctx`, or return a string or number to have it appended. Anything else
  * it returns is ignored, which is why the return type is `unknown` rather than `void | Scalar` - the
- * latter rejected `({ ctx }) => ctx.append(...)`, the form every virtual field is written in, because
+ * latter rejected `({ ctx }) => ctx.append(...)`, the form every computed field is written in, because
  * TypeScript's "returning a value where void is expected" allowance does not apply to a union.
  *
  * `Required`, and the parameter not optional, because the one place that calls it (`getRawValue`)

package/dist/type/universalQuerier.d.ts

@@ -153,14 +153,14 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return the ID
      */
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<EntityId<E> | undefined>;
     /**
      * Insert or update records.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<E> | undefined)[]>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.

package/dist/util/dialect.util.d.ts

@@ -1,6 +1,13 @@
 import { type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
+/** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
+/**
+ * The insertable keys `record` itself carries, as a string, for grouping rows by the statement they
+ * can share. Only the row's own keys: the `onInsert` columns {@link getInsertFieldKeys} appends are a
+ * property of the entity, identical for every row, so they cannot tell two rows apart.
+ */
+export declare function insertShapeOf<E>(meta: EntityMeta<E>, record: EntityData<E>): string;
 /**
  * Resolves the columns of an INSERT statement: the union of the persistable fields provided by
  * any record (in first-seen order), plus every `onInsert` field. Records missing one of these

package/dist/util/dialect.util.js

@@ -16,6 +16,20 @@ function isInsertableField(meta, record, key) {
     return !!field && !isDatabaseWritten(field) && record[key] !== undefined;
 }
 /** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
+/**
+ * The insertable keys `record` itself carries, as a string, for grouping rows by the statement they
+ * can share. Only the row's own keys: the `onInsert` columns {@link getInsertFieldKeys} appends are a
+ * property of the entity, identical for every row, so they cannot tell two rows apart.
+ */
+export function insertShapeOf(meta, record) {
+    let shape = '';
+    for (const key of getKeys(record)) {
+        if (isInsertableField(meta, record, key)) {
+            shape += `${key},`;
+        }
+    }
+    return shape;
+}
 function addInsertFieldKeys(meta, record, seen, keys) {
     for (const key of getKeys(record)) {
         if (!seen.has(key) && isInsertableField(meta, record, key)) {

package/dist/util/fieldOption.util.d.ts

@@ -34,7 +34,7 @@ declare const FIELD_OPTION_FAMILY: {
     readonly comment: '*';
 };
 /**
- * The only options a `virtual` field reaches: it is skipped in DDL and dropped from every insert and
+ * The only options an inlined computed field reaches: it is skipped in DDL and dropped from every insert and
  * update, so the whole persistence half of the options above is dead on one. Stated as what survives
  * rather than on each option that dies, because it is one fact rather than nineteen - and because an
  * option added without a thought then lands on the safe side of it.

package/dist/util/fieldOption.util.js

@@ -34,7 +34,7 @@ const FIELD_OPTION_FAMILY = {
     comment: '*',
 };
 /**
- * The only options a `virtual` field reaches: it is skipped in DDL and dropped from every insert and
+ * The only options an inlined computed field reaches: it is skipped in DDL and dropped from every insert and
  * update, so the whole persistence half of the options above is dead on one. Stated as what survives
  * rather than on each option that dies, because it is one fact rather than nineteen - and because an
  * option added without a thought then lands on the safe side of it.

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.47.1",
+  "version": "0.49.0",
   "type": "module",
   "engines": {
     "node": ">=24"