uql-orm 0.48.0 → 0.49.0

package/dist/entity/decorator/members.d.ts

@@ -1,4 +1,4 @@
-import type { EntityGetter, FieldOptions, FieldType, IdValue, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
+import type { EntityGetter, FieldOptions, FieldType, IdValue, NamedIdKey, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
 import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to. */
 type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext<unknown, V>) => void;
@@ -54,16 +54,28 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
     references: EntityGetter;
 }) & RejectUnknown<O, FieldOptions> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
- * Declares the primary key, checked the same way as `@Field`.
+ * A key the type level cannot name, reported on each `@Id` that leaves it unnamed. Where no `idKey`
+ * brand and no conventional name applies, `IdKey` falls back to every field, and `IdValue`,
+ * `EntityId` and every by-id method are then typed against a column that is not the key.
+ */
+type KeyIsNamed<This> = [NamedIdKey<This>] extends [never] ? {
+    readonly __keyNeedsIdKeyBrand: true;
+} : unknown;
+/** {@link MemberDecorator} that also constrains the class, which is where a key is named. */
+type IdDecorator<V> = <This>(value: undefined, context: ClassFieldDecoratorContext<This, V> & KeyIsNamed<This>) => void;
+/**
+ * Declares the primary key, checked the same way as `@Field` and additionally against the class:
+ * a key not named `id`, `_id` or `uuid` has to be named by the `idKey` brand.
  *
  * @example `@Id({ type: Number }) id?: number;`
  * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
+ * @example `[idKey]?: 'pk';` beside `@Id({ type: Number }) pk?: number;`
  */
 export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
     type: FieldType;
 } & RejectUnknown<O, FieldOptions> & RejectIncompatible<O> & {
     readonly nullable?: false;
-}>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+}>(opts: O): IdDecorator<DeclaredValue<O> | undefined>;
 /**
  * `E` comes from the mandatory `entity` getter, so the context can insist the property really holds that
  * entity: `@ManyToOne({ entity: () => Other })` on a `Company` field stops compiling, and a to-many

package/dist/entity/decorator/members.js

@@ -14,10 +14,12 @@ export function Field(opts) {
     };
 }
 /**
- * Declares the primary key, checked the same way as `@Field`.
+ * Declares the primary key, checked the same way as `@Field` and additionally against the class:
+ * a key not named `id`, `_id` or `uuid` has to be named by the `idKey` brand.
  *
  * @example `@Id({ type: Number }) id?: number;`
  * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
+ * @example `[idKey]?: 'pk';` beside `@Id({ type: Number }) pk?: number;`
  */
 export function Id(opts) {
     return (_value, context) => {

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.
  *

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.48.0",
+  "version": "0.49.0",
   "type": "module",
   "engines": {
     "node": ">=24"