@carno.js/orm 0.2.3

package/dist/domain/base-entity.d.ts

@@ -0,0 +1,57 @@
+import { SqlBuilder } from '../SqlBuilder';
+import { FilterQuery, FindOneOption, FindOptions, ValueOrInstance } from '../driver/driver.interface';
+export declare abstract class BaseEntity {
+    private _oldValues;
+    private _changedValues;
+    private $_isPersisted;
+    constructor();
+    /**
+     * Gets current entity's Repository.
+     */
+    static createQueryBuilder<T>(this: {
+        new (): T;
+    } & typeof BaseEntity): SqlBuilder<T>;
+    /**
+     * Gets current entity's Repository.
+     */
+    private createQueryBuilder;
+    static find<T, Hint extends string = never>(this: {
+        new (): T;
+    } & typeof BaseEntity, where: FilterQuery<T>, options?: FindOptions<T, Hint>): Promise<T[]>;
+    static findOne<T, Hint extends string = never>(this: {
+        new (): T;
+    } & typeof BaseEntity, where: FilterQuery<T>, options?: FindOneOption<T, Hint>): Promise<T | undefined>;
+    /**
+     * Find a record in the database based on the provided query where and return it, or throw an error if not found.
+     *
+     * @param {FilterQuery<T>} where - The query where used to search for the record.
+     * @param options
+     * @return {Promise<T>} - A promise that resolves with the found record.
+     */
+    static findOneOrFail<T, Hint extends string = never>(this: {
+        new (): T;
+    } & typeof BaseEntity, where: FilterQuery<T>, options?: FindOneOption<T, Hint>): Promise<T>;
+    static findAll<T extends object, Hint extends string = never>(this: {
+        new (): T;
+    } & typeof BaseEntity, options: FindOptions<T, Hint>): Promise<T[]>;
+    static create<T extends BaseEntity>(this: {
+        new (): T;
+    } & typeof BaseEntity, where: Partial<{
+        [K in keyof T]: ValueOrInstance<T[K]>;
+    }>): Promise<T>;
+    save(): Promise<void>;
+    /**
+     * Determines whether the current object has been persisted after the last modification.
+     *
+     * @return {boolean} Returns true if the object has been persisted, otherwise false.
+     */
+    isPersisted(): boolean;
+    toJSON(): Record<string, any>;
+    private serializeWithEntity;
+    private serializeWithMetadata;
+    private shouldSkipProperty;
+    private shouldSkipPropertyBasic;
+    private isInternalProperty;
+    private getHiddenPropertiesFromMetadata;
+    private addComputedProperties;
+}

package/dist/domain/base-entity.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseEntity = void 0;
+const SqlBuilder_1 = require("../SqlBuilder");
+const entities_1 = require("./entities");
+const core_1 = require("@carno.js/core");
+const constants_1 = require("../constants");
+class BaseEntity {
+    constructor() {
+        this._oldValues = {};
+        this._changedValues = {};
+        this.$_isPersisted = false;
+        return new Proxy(this, {
+            set(target, p, newValue) {
+                if (p.startsWith('$') || p.startsWith('_')) {
+                    target[p] = newValue;
+                    return true;
+                }
+                // se oldvalue não existir, é porque é a primeira vez que o atributo está sendo setado
+                if (!(p in target._oldValues)) {
+                    target._oldValues[p] = newValue;
+                }
+                // se o valor for diferente do valor antigo, é porque o valor foi alterado
+                if (target._oldValues[p] !== newValue) {
+                    target._changedValues[p] = newValue;
+                    this.$_isPersisted = false;
+                }
+                target[p] = newValue;
+                return true;
+            },
+        });
+    }
+    /**
+     * Gets current entity's Repository.
+     */
+    static createQueryBuilder() {
+        return new SqlBuilder_1.SqlBuilder(this);
+    }
+    /**
+     * Gets current entity's Repository.
+     */
+    createQueryBuilder() {
+        // @ts-ignore
+        return new SqlBuilder_1.SqlBuilder(this.constructor);
+    }
+    static async find(where, options) {
+        return this.createQueryBuilder()
+            .select(options?.fields)
+            .setStrategy(options?.loadStrategy)
+            .load(options?.load)
+            .where(where)
+            .limit(options?.limit)
+            .offset(options?.offset)
+            .orderBy(options?.orderBy)
+            .cache(options?.cache)
+            .executeAndReturnAll();
+    }
+    static async findOne(where, options) {
+        return this.createQueryBuilder()
+            .select(options?.fields)
+            .setStrategy(options?.loadStrategy)
+            .load(options?.load)
+            .where(where)
+            .cache(options?.cache)
+            .executeAndReturnFirst();
+    }
+    /**
+     * Find a record in the database based on the provided query where and return it, or throw an error if not found.
+     *
+     * @param {FilterQuery<T>} where - The query where used to search for the record.
+     * @param options
+     * @return {Promise<T>} - A promise that resolves with the found record.
+     */
+    static async findOneOrFail(where, options) {
+        return this.createQueryBuilder()
+            // @ts-ignore
+            .select(options?.fields)
+            .setStrategy(options?.loadStrategy)
+            .load(options?.load)
+            .where(where)
+            .orderBy(options?.orderBy)
+            .cache(options?.cache)
+            .executeAndReturnFirstOrFail();
+    }
+    static async findAll(options) {
+        const builder = this.createQueryBuilder()
+            .select(options.fields)
+            .setStrategy(options?.loadStrategy)
+            .load(options?.load)
+            .offset(options?.offset)
+            .limit(options.limit)
+            .orderBy(options?.orderBy)
+            .cache(options?.cache);
+        return builder.executeAndReturnAll();
+    }
+    static async create(where) {
+        return this.createQueryBuilder()
+            .insert(where)
+            .executeAndReturnFirstOrFail();
+    }
+    async save() {
+        const qb = this.createQueryBuilder();
+        if (this.$_isPersisted) {
+            qb.update(this._changedValues);
+            qb.setInstance(this);
+            // @ts-ignore
+            qb.where({ id: this._oldValues.id });
+        }
+        else {
+            qb.insert(this._oldValues);
+        }
+        await qb.execute();
+        qb.callHook('afterCreate', this);
+        qb.callHook('afterUpdate', this);
+        this._oldValues = {
+            ...this._oldValues,
+            ...this._changedValues,
+        };
+        this._changedValues = {};
+    }
+    /**
+     * Determines whether the current object has been persisted after the last modification.
+     *
+     * @return {boolean} Returns true if the object has been persisted, otherwise false.
+     */
+    isPersisted() {
+        return this.$_isPersisted;
+    }
+    toJSON() {
+        const storage = entities_1.EntityStorage.getInstance();
+        const entity = storage.get(this.constructor);
+        const data = entity
+            ? this.serializeWithEntity(entity)
+            : this.serializeWithMetadata();
+        this.addComputedProperties(data);
+        return data;
+    }
+    serializeWithEntity(entity) {
+        const data = {};
+        const allProperties = new Set(Object.keys(entity.properties));
+        const allRelations = new Set((entity.relations || []).map((relation) => relation.propertyKey));
+        const hidePropertiesSet = new Set(entity.hideProperties);
+        for (const key in this) {
+            if (this.shouldSkipProperty(key, allProperties, allRelations, hidePropertiesSet)) {
+                continue;
+            }
+            data[key] = this[key];
+        }
+        return data;
+    }
+    serializeWithMetadata() {
+        const data = {};
+        const hideProperties = this.getHiddenPropertiesFromMetadata();
+        const hidePropertiesSet = new Set(hideProperties);
+        for (const key in this) {
+            if (this.shouldSkipPropertyBasic(key, hidePropertiesSet)) {
+                continue;
+            }
+            data[key] = this[key];
+        }
+        return data;
+    }
+    shouldSkipProperty(key, allProperties, allRelations, hideProperties) {
+        if (this.isInternalProperty(key)) {
+            return true;
+        }
+        if (!allProperties.has(key) && !allRelations.has(key)) {
+            return true;
+        }
+        return hideProperties.has(key);
+    }
+    shouldSkipPropertyBasic(key, hideProperties) {
+        if (this.isInternalProperty(key)) {
+            return true;
+        }
+        return hideProperties.has(key);
+    }
+    isInternalProperty(key) {
+        return key.startsWith('$') || key.startsWith('_');
+    }
+    getHiddenPropertiesFromMetadata() {
+        const properties = core_1.Metadata.get(constants_1.PROPERTIES_METADATA, this.constructor) || {};
+        const hideProperties = [];
+        for (const [key, prop] of Object.entries(properties)) {
+            if (prop.options?.hidden) {
+                hideProperties.push(key);
+            }
+        }
+        return hideProperties;
+    }
+    addComputedProperties(data) {
+        const computedProperties = core_1.Metadata.get(constants_1.COMPUTED_PROPERTIES, this.constructor) || [];
+        for (const key of computedProperties) {
+            data[key] = this[key];
+        }
+    }
+}
+exports.BaseEntity = BaseEntity;

package/dist/domain/collection.d.ts

@@ -0,0 +1,6 @@
+export declare class ArrayCollection<T extends object, O extends object> {
+    getItems(): T[];
+}
+export declare class Collection<T extends object, O extends object = object> extends ArrayCollection<T, O> {
+    constructor(owner: O, items?: T[], initialized?: boolean);
+}

package/dist/domain/collection.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Collection = exports.ArrayCollection = void 0;
+class ArrayCollection {
+    getItems() {
+        return [];
+    }
+}
+exports.ArrayCollection = ArrayCollection;
+class Collection extends ArrayCollection {
+    constructor(owner, items, initialized = true) {
+        super();
+    }
+}
+exports.Collection = Collection;

package/dist/domain/entities.d.ts

@@ -0,0 +1,49 @@
+import { PropertyOptions } from "../decorators/property.decorator";
+import { Relationship, SnapshotIndexInfo, SnapshotTable, SnapshotUniqueInfo } from "../driver/driver.interface";
+export type Property = {
+    options: PropertyOptions;
+    type: Function;
+};
+export type Options = {
+    properties: {
+        [key: string]: Property;
+    };
+    hideProperties: string[];
+    indexes?: SnapshotIndexInfo[];
+    uniques?: SnapshotUniqueInfo[];
+    relations: Relationship<any>[];
+    tableName: string;
+    hooks?: {
+        type: string;
+        propertyName: string;
+    }[];
+    schema?: string;
+};
+export declare class EntityStorage {
+    static instance: EntityStorage;
+    private entities;
+    constructor();
+    add(entity: {
+        target: Function;
+        options: any;
+    }, properties: {
+        [key: string]: Property;
+    }, relations: Relationship<any>[], hooks: {
+        type: string;
+        propertyName: string;
+    }[]): void;
+    get(entity: Function): Options;
+    entries(): MapIterator<[Function, Options]>;
+    static getInstance(): EntityStorage;
+    snapshot(values: Options): Promise<SnapshotTable>;
+    private snapshotColumns;
+    private snapshotIndexes;
+    private getFkType;
+    private getFkIncrement;
+    /**
+     * If fkKey is null, return the primary key of the entity
+     * @private
+     * @param relationShip
+     */
+    private getFkKey;
+}

package/dist/domain/entities.js

@@ -0,0 +1,259 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var EntityStorage_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityStorage = void 0;
+const core_1 = require("@carno.js/core");
+const orm_session_context_1 = require("../orm-session-context");
+const utils_1 = require("../utils");
+const index_condition_builder_1 = require("../query/index-condition-builder");
+function buildIndexColumnMap(properties, relations) {
+    const map = mapPropertyColumns(properties);
+    addRelationColumns(map, relations);
+    return map;
+}
+function mapPropertyColumns(properties) {
+    const map = {};
+    Object.entries(properties).forEach(([key, value]) => {
+        map[key] = value.options.columnName;
+    });
+    return map;
+}
+function addRelationColumns(map, relations) {
+    relations.forEach((relation) => {
+        map[String(relation.propertyKey)] = relation.columnName;
+    });
+}
+function mapIndexDefinitions(indexes, entityName, columnMap) {
+    return indexes.map((index) => toSnapshotIndex(index, entityName, columnMap));
+}
+function toSnapshotIndex(index, entityName, columnMap) {
+    const columns = resolveIndexColumns(index, columnMap);
+    const indexName = resolveIndexName(index.name, entityName, columns);
+    return {
+        table: entityName,
+        indexName,
+        columnName: columns.join(","),
+        where: resolveIndexWhere(index.where, columnMap),
+    };
+}
+function resolveIndexColumns(index, columnMap) {
+    return index.properties.map((propName) => resolveIndexColumn(propName, columnMap));
+}
+function resolveIndexColumn(propName, columnMap) {
+    const mapped = columnMap[propName];
+    if (mapped) {
+        return mapped;
+    }
+    return (0, utils_1.toSnakeCase)(propName);
+}
+function resolveIndexName(name, entityName, columns) {
+    if (name.includes('_pkey') || name.includes('[TABLE]')) {
+        return name.replace("[TABLE]", entityName);
+    }
+    return `${columns.join("_")}_index`;
+}
+function resolveIndexWhere(where, columnMap) {
+    if (!where) {
+        return undefined;
+    }
+    if (typeof where === "string") {
+        return where;
+    }
+    if (typeof where === "function") {
+        return where(columnMap);
+    }
+    return buildIndexWhere(where, columnMap);
+}
+function buildIndexWhere(where, columnMap) {
+    const builder = new index_condition_builder_1.IndexConditionBuilder(columnMap);
+    return builder.build(where);
+}
+function mapUniqueDefinitions(uniques, entityName, columnMap) {
+    return uniques.map((unique) => toSnapshotUnique(unique, entityName, columnMap));
+}
+function toSnapshotUnique(unique, entityName, columnMap) {
+    const columns = resolveUniqueColumns(unique, columnMap);
+    const uniqueName = resolveUniqueName(unique.name, entityName, columns);
+    return {
+        table: entityName,
+        uniqueName,
+        columnName: columns.join(","),
+    };
+}
+function resolveUniqueColumns(unique, columnMap) {
+    return unique.properties.map((propName) => resolveUniqueColumn(propName, columnMap));
+}
+function resolveUniqueColumn(propName, columnMap) {
+    const mapped = columnMap[propName];
+    if (mapped) {
+        return mapped;
+    }
+    return (0, utils_1.toSnakeCase)(propName);
+}
+function resolveUniqueName(name, entityName, columns) {
+    return `${columns.join("_")}_unique`;
+}
+let EntityStorage = EntityStorage_1 = class EntityStorage {
+    constructor() {
+        this.entities = new Map();
+        EntityStorage_1.instance = this;
+    }
+    add(entity, properties, relations, hooks) {
+        const entityName = entity.options?.tableName || (0, utils_1.toSnakeCase)(entity.target.name);
+        const indexes = core_1.Metadata.get("indexes", entity.target) || [];
+        const uniques = core_1.Metadata.get("uniques", entity.target) || [];
+        const columnMap = buildIndexColumnMap(properties, relations);
+        this.entities.set(entity.target, {
+            properties: properties,
+            hideProperties: Object.entries(properties)
+                .filter(([_key, value]) => value.options.hidden)
+                .map(([key]) => key),
+            relations,
+            indexes: mapIndexDefinitions(indexes, entityName, columnMap),
+            uniques: mapUniqueDefinitions(uniques, entityName, columnMap),
+            hooks,
+            tableName: entityName,
+            ...entity.options,
+        });
+    }
+    get(entity) {
+        return this.entities.get(entity);
+    }
+    entries() {
+        return this.entities.entries();
+    }
+    static getInstance() {
+        const scoped = orm_session_context_1.ormSessionContext.getStorage();
+        if (scoped) {
+            return scoped;
+        }
+        return EntityStorage_1.instance;
+    }
+    async snapshot(values) {
+        return {
+            tableName: values.tableName,
+            schema: values.schema || "public",
+            indexes: values.indexes || [],
+            uniques: values.uniques || [],
+            columns: this.snapshotColumns(values),
+        };
+    }
+    snapshotColumns(values) {
+        let properties = Object.entries(values.properties).map(([_key, value]) => {
+            return {
+                name: value.options.columnName,
+                type: value.options.dbType ?? value.type.name,
+                nullable: value.options?.nullable,
+                default: value.options?.default,
+                autoIncrement: value.options?.autoIncrement,
+                primary: value.options?.isPrimary,
+                unique: value.options?.unique,
+                length: value.options?.length,
+                isEnum: value.options?.isEnum,
+                precision: value.options?.precision,
+                scale: value.options?.scale,
+                enumItems: value.options?.enumItems,
+            };
+        });
+        // @ts-ignore
+        let relations = values.relations &&
+            values.relations
+                .filter((relation) => relation.relation === 'many-to-one')
+                .map((relation) => {
+                const type = this.getFkType(relation);
+                return {
+                    name: relation.columnName,
+                    type,
+                    nullable: relation.nullable,
+                    unique: relation.unique,
+                    length: relation.length || (0, utils_1.getDefaultLength)(type),
+                    default: relation.default,
+                    autoIncrement: relation.autoIncrement,
+                    primary: relation.isPrimary,
+                    precision: relation.precision,
+                    scale: relation.scale,
+                    foreignKeys: [
+                        {
+                            referencedColumnName: this.getFkKey(relation),
+                            referencedTableName: this.get(relation.entity()).tableName,
+                        },
+                    ],
+                };
+            });
+        if (!relations) {
+            relations = [];
+        }
+        if (!properties) {
+            properties = [];
+        }
+        return [...properties, ...relations];
+    }
+    snapshotIndexes(values) {
+        return Object.entries(values.properties).map(([key, _value]) => {
+            return {
+                indexName: key,
+                columnName: key,
+                table: values.tableName,
+            };
+        });
+    }
+    getFkType(relation) {
+        const entity = this.get(relation.entity());
+        if (!entity) {
+            return "unknown";
+        }
+        const foreignKey = this.getFkKey(relation);
+        const property = entity.properties[foreignKey];
+        if (!property) {
+            return "unknown";
+        }
+        if (property.options?.dbType) {
+            return property.options.dbType;
+        }
+        return property.type?.name ?? "unknown";
+    }
+    getFkIncrement(relation) {
+        const entity = this.get(relation.entity());
+        if (!entity) {
+            return "unknown";
+        }
+        return entity.properties[this.getFkKey(relation)].options.autoIncrement;
+    }
+    /**
+     * If fkKey is null, return the primary key of the entity
+     * @private
+     * @param relationShip
+     */
+    getFkKey(relationShip) {
+        // se for nullable, deverá retornar o primary key da entidade target
+        if (typeof relationShip.fkKey === "undefined") {
+            const entity = this.entities.get(relationShip.entity());
+            const property = Object.entries(entity.properties).find(([_key, value]) => value.options.isPrimary === true);
+            if (!property) {
+                throw new Error(`Entity ${entity.tableName} does not have a primary key`);
+            }
+            return property[0];
+        }
+        // se o fkKey é uma função, ele retornará a propriedade da entidade que é a chave estrangeira
+        // precisamos pegar o nome dessa propriedade
+        if (typeof relationShip.fkKey === "string") {
+            return relationShip.fkKey;
+        }
+        const match = /\.(?<propriedade>[\w]+)/.exec(relationShip.fkKey.toString());
+        return match ? match.groups.propriedade : "";
+    }
+};
+exports.EntityStorage = EntityStorage;
+exports.EntityStorage = EntityStorage = EntityStorage_1 = __decorate([
+    (0, core_1.Service)(),
+    __metadata("design:paramtypes", [])
+], EntityStorage);

package/dist/domain/reference.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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;
+}
+/**
+ * Creates a lightweight entity reference by class and id without hitting the DB.
+ * Useful to assign many-to-one relations when only the id is known.
+ *
+ * Example:
+ *   const library = await UserLibrary.create({
+ *     user: refById(User, userId),
+ *     course: refById(Course, courseId),
+ *   });
+ */
+export declare function refById<C extends new () => any, T = InstanceType<C>, PK = any>(Cls: C, id: PK): T;