@cheetah.js/orm 0.1.69 → 0.1.71

package/dist/domain/reference.d.ts

@@ -1,4 +1,75 @@
+/**
+ * Transparent wrapper type to prevent circular dependencies in TypeScript.
+ *
+ * @example
+ * ```typescript
+ * // Instead of direct import causing circular dependency:
+ * import { User } from './User';
+ * class Post {
+ *   @ManyToOne()
+ *   author: User; // Circular dependency!
+ * }
+ *
+ * // Use Ref to break the cycle:
+ * import type { User } from './User';
+ * class Post {
+ *   @ManyToOne()
+ *   author: Ref<User>; // No circular dependency!
+ * }
+ * ```
+ */
+export type Ref<T> = T;
+/**
+ * Creates a reference to an entity.
+ * This is an identity function - it returns the input unchanged.
+ * Useful for explicit ref creation when needed.
+ *
+ * @param entity - The entity to wrap in a reference
+ * @returns The same entity (identity function)
+ *
+ * @example
+ * ```typescript
+ * const user = new User();
+ * const userRef = ref(user); // userRef === user (same reference)
+ * ```
+ */
+export declare function ref<T>(entity: T): Ref<T>;
+/**
+ * Unwraps a reference to get the underlying entity.
+ * This is an identity function - it returns the input unchanged.
+ * Provided for API consistency and explicitness.
+ *
+ * @param reference - The reference to unwrap
+ * @returns The underlying entity (same as input)
+ *
+ * @example
+ * ```typescript
+ * const post = await Post.findOne({ id: 1 });
+ * const author = unwrap(post.author); // author === post.author
+ * ```
+ */
+export declare function unwrap<T>(reference: Ref<T>): T;
+/**
+ * Type guard to check if a value is not null or undefined.
+ * Useful when working with optional references.
+ *
+ * @param value - The value to check
+ * @returns True if value is not null/undefined
+ *
+ * @example
+ * ```typescript
+ * const post = await Post.findOne({ id: 1 });
+ * if (isLoaded(post.author)) {
+ *   console.log(post.author.name); // TypeScript knows author is defined
+ * }
+ * ```
+ */
+export declare function isLoaded<T>(value: Ref<T> | null | undefined): value is Ref<T>;
+/**
+ * @deprecated Use `Ref<T>` type instead. This class is kept for backward compatibility.
+ */
 export declare class Reference<T> {
     private entity;
     constructor(entity: T);
+    get(): T;
 }

package/dist/domain/reference.js

@@ -1,10 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Reference = void 0;
+exports.ref = ref;
+exports.unwrap = unwrap;
+exports.isLoaded = isLoaded;
+/**
+ * Creates a reference to an entity.
+ * This is an identity function - it returns the input unchanged.
+ * Useful for explicit ref creation when needed.
+ *
+ * @param entity - The entity to wrap in a reference
+ * @returns The same entity (identity function)
+ *
+ * @example
+ * ```typescript
+ * const user = new User();
+ * const userRef = ref(user); // userRef === user (same reference)
+ * ```
+ */
+function ref(entity) {
+    return entity;
+}
+/**
+ * Unwraps a reference to get the underlying entity.
+ * This is an identity function - it returns the input unchanged.
+ * Provided for API consistency and explicitness.
+ *
+ * @param reference - The reference to unwrap
+ * @returns The underlying entity (same as input)
+ *
+ * @example
+ * ```typescript
+ * const post = await Post.findOne({ id: 1 });
+ * const author = unwrap(post.author); // author === post.author
+ * ```
+ */
+function unwrap(reference) {
+    return reference;
+}
+/**
+ * Type guard to check if a value is not null or undefined.
+ * Useful when working with optional references.
+ *
+ * @param value - The value to check
+ * @returns True if value is not null/undefined
+ *
+ * @example
+ * ```typescript
+ * const post = await Post.findOne({ id: 1 });
+ * if (isLoaded(post.author)) {
+ *   console.log(post.author.name); // TypeScript knows author is defined
+ * }
+ * ```
+ */
+function isLoaded(value) {
+    return value != null;
+}
+/**
+ * @deprecated Use `Ref<T>` type instead. This class is kept for backward compatibility.
+ */
 class Reference {
     constructor(entity) {
         this.entity = entity;
-        console.log('Reference constructor');
+    }
+    get() {
+        return this.entity;
     }
 }
 exports.Reference = Reference;

package/dist/driver/driver.interface.d.ts

@@ -266,13 +266,9 @@ export type Relationship<T> = {
 } & Partial<PropertyOptions>;
 export type Cast<T, R> = T extends R ? T : R;
 export type IsUnknown<T> = T extends unknown ? unknown extends T ? true : never : never;
-export type IdentifiedReference<T, PK extends keyof T | unknown = PrimaryProperty<T>> = true extends IsUnknown<PK> ? Reference<T> : ({
-    [K in Cast<PK, keyof T>]: T[K];
-} & Reference<T>);
-export type Ref<T, PK extends keyof T | unknown = PrimaryProperty<T>> = IdentifiedReference<T, PK>;
 type Loadable<T extends object> = Collection<T, any> | Reference<T> | readonly T[];
 type ExtractType<T> = T extends Loadable<infer U> ? U : T;
-type StringKeys<T, E extends string = never> = T extends Collection<any, any> ? `${Exclude<keyof ExtractType<T> | E, symbol>}` : T extends Ref<any> ? `${Exclude<keyof ExtractType<T> | E, symbol>}` : T extends object ? `${Exclude<keyof ExtractType<T> | E, symbol>}` : never;
+type StringKeys<T, E extends string = never> = T extends Collection<any, any> ? `${Exclude<keyof ExtractType<T> | E, symbol>}` : T extends Reference<any> ? `${Exclude<keyof ExtractType<T> | E, symbol>}` : T extends object ? `${Exclude<keyof ExtractType<T> | E, symbol>}` : never;
 type Defined<T> = Exclude<T, null | undefined>;
 type GetStringKey<T, K extends StringKeys<T, string>, E extends string> = K extends keyof T ? ExtractType<T[K]> : (K extends E ? keyof T : never);
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './decorators/enum.decorator';
 export * from './orm';
 export * from './orm.service';
 export * from './domain/base-entity';
+export * from './domain/reference';
 export { EntityStorage } from './domain/entities';
 export * from './driver/bun-pg.driver';
 export * from './driver/bun-mysql.driver';

package/dist/index.js

@@ -25,6 +25,7 @@ __exportStar(require("./decorators/enum.decorator"), exports);
 __exportStar(require("./orm"), exports);
 __exportStar(require("./orm.service"), exports);
 __exportStar(require("./domain/base-entity"), exports);
+__exportStar(require("./domain/reference"), exports);
 var entities_1 = require("./domain/entities");
 Object.defineProperty(exports, "EntityStorage", { enumerable: true, get: function () { return entities_1.EntityStorage; } });
 __exportStar(require("./driver/bun-pg.driver"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cheetah.js/orm",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "A simple ORM for Cheetah.js",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -55,5 +55,5 @@
     "bun",
     "value-object"
   ],
-  "gitHead": "428078677b3e778486cd6170f644f10ac90489e3"
+  "gitHead": "45c36a4d8125e8937524a7a586bda671ef7725e3"
 }