ts-prorm-orm 1.1.0 → 1.2.0

package/dist/graph/types.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Shared types and helpers for the ORM's graph/object-database dialects
+ * (Neo4j, Gremlin/TinkerPop/Neptune, Dgraph).
+ *
+ * These live under `src/graph/` and are intentionally self-contained: the
+ * graph dialects reuse the SQL-shaped `Dialect` contract (so the same
+ * `Model` builder API drives them) but express everything as graph
+ * primitives — node labels, edges/relationships, and traversals — instead
+ * of tables and joins. Nothing here edits shared base files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParamBag = exports.GraphCapabilityError = void 0;
+exports.normalizeWhere = normalizeWhere;
+exports.deriveAssociationEdge = deriveAssociationEdge;
+exports.defaultEdgeLabel = defaultEdgeLabel;
+exports.safeIdent = safeIdent;
+const index_1 = require("../errors/index");
+const operators_1 = require("../operators");
+/**
+ * Typed error thrown when a relational feature has no meaningful graph
+ * equivalent and cannot be emulated via traversal (e.g. arbitrary SQL joins
+ * on a pure graph, materialized views, row-level-security policies).
+ */
+class GraphCapabilityError extends index_1.DatabaseError {
+    constructor(feature, dialect) {
+        super(`"${feature}" is not supported by the ${dialect} graph dialect`, {
+            code: index_1.ErrorCodes.DATABASE_ERROR,
+            original: feature,
+        });
+        this.name = 'GraphCapabilityError';
+        this.feature = feature;
+        this.dialect = dialect;
+    }
+}
+exports.GraphCapabilityError = GraphCapabilityError;
+/**
+ * Allocates unique, ordered parameter names and collects their values.
+ * Produces both a named-param map (for Cypher `$p0` / DQL `$p0` / Gremlin
+ * bindings) and, via {@link toArray}, a positional array for the SQL-shaped
+ * `{ sql, values }` return contract.
+ */
+class ParamBag {
+    constructor(prefix = 'p') {
+        this.prefix = prefix;
+        this.index = 0;
+        this.params = {};
+        this.names = [];
+    }
+    add(value) {
+        const name = `${this.prefix}${this.index++}`;
+        this.params[name] = value;
+        this.names.push(name);
+        return name;
+    }
+    toArray() {
+        return this.names.map((n) => this.params[n]);
+    }
+}
+exports.ParamBag = ParamBag;
+// Map every relevant `Op` symbol to a canonical operator name.
+const OP_SYMBOL_TO_CANON = new Map([
+    [operators_1.Op.eq, 'eq'],
+    [operators_1.Op.is, 'eq'],
+    [operators_1.Op.ne, 'ne'],
+    [operators_1.Op.gt, 'gt'],
+    [operators_1.Op.gte, 'gte'],
+    [operators_1.Op.lt, 'lt'],
+    [operators_1.Op.lte, 'lte'],
+    [operators_1.Op.in, 'in'],
+    [operators_1.Op.notIn, 'notIn'],
+    [operators_1.Op.like, 'like'],
+    [operators_1.Op.notLike, 'notLike'],
+    [operators_1.Op.iLike, 'iLike'],
+    [operators_1.Op.notILike, 'notILike'],
+    [operators_1.Op.between, 'between'],
+    [operators_1.Op.notBetween, 'notBetween'],
+    [operators_1.Op.regexp, 'regexp'],
+    [operators_1.Op.notRegexp, 'notRegexp'],
+    [operators_1.Op.startsWith, 'startsWith'],
+    [operators_1.Op.notStartsWith, 'notStartsWith'],
+    [operators_1.Op.endsWith, 'endsWith'],
+    [operators_1.Op.notEndsWith, 'notEndsWith'],
+    [operators_1.Op.substring, 'substring'],
+    [operators_1.Op.notSubstring, 'notSubstring'],
+]);
+const STRING_OP_TO_CANON = {
+    $eq: 'eq',
+    $ne: 'ne',
+    $gt: 'gt',
+    $gte: 'gte',
+    $lt: 'lt',
+    $lte: 'lte',
+    $in: 'in',
+    $notIn: 'notIn',
+    $like: 'like',
+    $notLike: 'notLike',
+    $iLike: 'iLike',
+    $between: 'between',
+    $notBetween: 'notBetween',
+    $regexp: 'regexp',
+    $notRegexp: 'notRegexp',
+    $startsWith: 'startsWith',
+    $endsWith: 'endsWith',
+    $substring: 'substring',
+};
+function isPlainValue(v) {
+    return (v === null ||
+        v === undefined ||
+        typeof v === 'string' ||
+        typeof v === 'number' ||
+        typeof v === 'boolean' ||
+        v instanceof Date ||
+        Array.isArray(v));
+}
+/**
+ * Convert a field-level value (scalar, array, or `{ [Op.x]: value }` object)
+ * into one or more comparison predicates for `field`.
+ */
+function fieldToPredicates(field, value) {
+    if (value === null) {
+        return [{ kind: 'cmp', field, op: 'isNull', value: null }];
+    }
+    if (isPlainValue(value)) {
+        return [{ kind: 'cmp', field, op: 'eq', value }];
+    }
+    if (typeof value === 'object') {
+        const preds = [];
+        const obj = value;
+        // Symbol-keyed operators (Op.gte, Op.in, ...).
+        for (const sym of Object.getOwnPropertySymbols(obj)) {
+            const opVal = obj[sym];
+            if (sym === operators_1.Op.isNull) {
+                preds.push({ kind: 'cmp', field, op: 'isNull', value: null });
+                continue;
+            }
+            if (sym === operators_1.Op.isNotNull) {
+                preds.push({ kind: 'cmp', field, op: 'isNotNull', value: null });
+                continue;
+            }
+            const canon = OP_SYMBOL_TO_CANON.get(sym);
+            if (canon) {
+                preds.push({ kind: 'cmp', field, op: canon, value: opVal });
+            }
+        }
+        // String-keyed operators ($gte, $in, ...).
+        for (const key of Object.keys(obj)) {
+            const canon = STRING_OP_TO_CANON[key];
+            if (canon) {
+                preds.push({ kind: 'cmp', field, op: canon, value: obj[key] });
+            }
+        }
+        if (preds.length === 0) {
+            // No recognized operators: treat as an equality against the object.
+            return [{ kind: 'cmp', field, op: 'eq', value }];
+        }
+        return preds;
+    }
+    return [{ kind: 'cmp', field, op: 'eq', value }];
+}
+/**
+ * Normalize an ORM `WhereOptions` (mixing `Op.*` symbols, `$and`/`$or`/
+ * `$not`, and plain equality) into a {@link GraphPredicate} tree. Returns a
+ * `{ kind: 'true' }` node for an empty/absent filter.
+ */
+function normalizeWhere(where) {
+    if (!where || typeof where !== 'object') {
+        return { kind: 'true' };
+    }
+    const items = [];
+    const obj = where;
+    // Symbol logical operators: Op.and / Op.or / Op.not.
+    for (const sym of Object.getOwnPropertySymbols(obj)) {
+        const v = obj[sym];
+        if (sym === operators_1.Op.and && Array.isArray(v)) {
+            items.push({ kind: 'and', items: v.map((w) => normalizeWhere(w)) });
+        }
+        else if (sym === operators_1.Op.or && Array.isArray(v)) {
+            items.push({ kind: 'or', items: v.map((w) => normalizeWhere(w)) });
+        }
+        else if (sym === operators_1.Op.not) {
+            items.push({ kind: 'not', item: normalizeWhere(v) });
+        }
+    }
+    for (const key of Object.keys(obj)) {
+        const v = obj[key];
+        if (key === '$and' && Array.isArray(v)) {
+            items.push({ kind: 'and', items: v.map((w) => normalizeWhere(w)) });
+        }
+        else if (key === '$or' && Array.isArray(v)) {
+            items.push({ kind: 'or', items: v.map((w) => normalizeWhere(w)) });
+        }
+        else if (key === '$not') {
+            items.push({ kind: 'not', item: normalizeWhere(v) });
+        }
+        else {
+            items.push(...fieldToPredicates(key, v));
+        }
+    }
+    if (items.length === 0) {
+        return { kind: 'true' };
+    }
+    if (items.length === 1) {
+        return items[0];
+    }
+    return { kind: 'and', items };
+}
+/**
+ * Derive a graph edge from an ORM association descriptor (as produced by
+ * `Model.hasMany`/`belongsTo`/etc.). Accepts a loose shape so it works with
+ * either the ORM's association objects or a plain {@link GraphAssociationSpec}.
+ */
+function deriveAssociationEdge(assoc) {
+    const rawType = (assoc.associationType || assoc.type || 'hasMany');
+    const type = (['hasMany', 'hasOne', 'belongsTo', 'belongsToMany'].includes(rawType)
+        ? rawType
+        : 'hasMany');
+    const targetName = typeof assoc.target === 'string'
+        ? assoc.target
+        : assoc.target?.label || assoc.target?.name || assoc.as || 'Node';
+    const as = assoc.as || targetName;
+    const direction = assoc.direction ?? (type === 'belongsTo' ? 'in' : 'out');
+    const edgeLabel = assoc.edgeLabel || defaultEdgeLabel(as);
+    return { type, as, target: targetName, edgeLabel, direction };
+}
+/** Default edge label for an association name, e.g. `posts` -> `HAS_POSTS`. */
+function defaultEdgeLabel(as) {
+    return `HAS_${as.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/[\s-]+/g, '_').toUpperCase()}`;
+}
+/** Sanitize an identifier (label/property/edge) to a safe `[A-Za-z0-9_]` token. */
+function safeIdent(name) {
+    const cleaned = String(name).replace(/[^A-Za-z0-9_]/g, '_');
+    return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned;
+}

package/dist/hooks/hooks-manager.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Hooks Manager for the TypeScript ORM
+ * Provides a centralized system for managing Prorm-style model hooks
+ */
+import { HookOptions, HookHandler, BulkHookHandler } from '../types';
+export type HookName = 'beforeValidate' | 'afterValidate' | 'beforeCreate' | 'afterCreate' | 'beforeUpdate' | 'afterUpdate' | 'beforeDestroy' | 'afterDestroy' | 'beforeSave' | 'afterSave' | 'beforeBulkCreate' | 'afterBulkCreate' | 'beforeBulkUpdate' | 'afterBulkUpdate' | 'beforeBulkDestroy' | 'afterBulkDestroy' | 'beforeFind' | 'afterFind';
+export type HookCallback = HookHandler | BulkHookHandler | FindHookHandler;
+export interface FindHookHandler {
+    (options: FindHookOptions): Promise<void> | void;
+}
+export interface FindHookOptions extends HookOptions {
+    where?: Record<string, any>;
+    attributes?: string[];
+    include?: any[];
+    order?: any;
+    limit?: number | string;
+    offset?: number | string;
+    model?: any;
+}
+export type HooksMap = Map<HookName, Set<HookCallback>>;
+/**
+ * HooksManager - Manages all lifecycle hooks for a model
+ */
+export declare class HooksManager {
+    private hooks;
+    private modelName;
+    constructor(modelName?: string);
+    /**
+     * Initialize all hook types as empty Sets
+     */
+    private initializeHooks;
+    /**
+     * Get all hooks
+     */
+    getHooks(): HooksMap;
+    /**
+     * Get hooks for a specific hook name
+     */
+    getHook(hookName: HookName): Set<HookCallback>;
+    /**
+     * Add a hook callback
+     */
+    addHook(hookName: string, callback: HookCallback): this;
+    /**
+     * Remove a hook callback
+     */
+    removeHook(hookName: string, callback: HookCallback): this;
+    /**
+     * Run all callbacks for a specific hook
+     */
+    runHook(hookName: string, ...args: any[]): Promise<void>;
+    /**
+     * Check if a hook has registered callbacks
+     */
+    hasHook(hookName: string): boolean;
+    /**
+     * Get the count of hooks for a specific hook name
+     */
+    getHookCount(hookName: string): number;
+    /**
+     * Clear all hooks
+     */
+    clearHooks(): this;
+    /**
+     * Clear hooks for a specific hook name
+     */
+    clearHook(hookName: string): this;
+    /**
+     * Normalize hook name to camelCase
+     */
+    private normalizeHookName;
+}
+/**
+ * Create a hooks object compatible with Model options
+ */
+export declare function createHooksObject(hooksManager: HooksManager): Record<string, HookCallback>;
+/**
+ * Mixin function to add hook methods to a Model class
+ */
+export declare function addHookMethods<T extends HooksManager>(target: any, hooksManager: T): void;
+/**
+ * Create a beforeValidate hook wrapper
+ */
+export declare function beforeValidate(callback: HookHandler): {
+    beforeValidate: HookHandler;
+};
+/**
+ * Create an afterValidate hook wrapper
+ */
+export declare function afterValidate(callback: HookHandler): {
+    afterValidate: HookHandler;
+};
+/**
+ * Create a beforeCreate hook wrapper
+ */
+export declare function beforeCreate(callback: HookHandler): {
+    beforeCreate: HookHandler;
+};
+/**
+ * Create an afterCreate hook wrapper
+ */
+export declare function afterCreate(callback: HookHandler): {
+    afterCreate: HookHandler;
+};
+/**
+ * Create a beforeUpdate hook wrapper
+ */
+export declare function beforeUpdate(callback: HookHandler): {
+    beforeUpdate: HookHandler;
+};
+/**
+ * Create an afterUpdate hook wrapper
+ */
+export declare function afterUpdate(callback: HookHandler): {
+    afterUpdate: HookHandler;
+};
+/**
+ * Create a beforeDestroy hook wrapper
+ */
+export declare function beforeDestroy(callback: HookHandler): {
+    beforeDestroy: HookHandler;
+};
+/**
+ * Create an afterDestroy hook wrapper
+ */
+export declare function afterDestroy(callback: HookHandler): {
+    afterDestroy: HookHandler;
+};
+/**
+ * Create a beforeSave hook wrapper
+ */
+export declare function beforeSave(callback: HookHandler): {
+    beforeSave: HookHandler;
+};
+/**
+ * Create an afterSave hook wrapper
+ */
+export declare function afterSave(callback: HookHandler): {
+    afterSave: HookHandler;
+};
+/**
+ * Create a beforeBulkCreate hook wrapper
+ */
+export declare function beforeBulkCreate(callback: BulkHookHandler): {
+    beforeBulkCreate: BulkHookHandler;
+};
+/**
+ * Create an afterBulkCreate hook wrapper
+ */
+export declare function afterBulkCreate(callback: BulkHookHandler): {
+    afterBulkCreate: BulkHookHandler;
+};
+/**
+ * Create a beforeBulkUpdate hook wrapper
+ */
+export declare function beforeBulkUpdate(callback: BulkHookHandler): {
+    beforeBulkUpdate: BulkHookHandler;
+};
+/**
+ * Create an afterBulkUpdate hook wrapper
+ */
+export declare function afterBulkUpdate(callback: BulkHookHandler): {
+    afterBulkUpdate: BulkHookHandler;
+};
+/**
+ * Create a beforeBulkDestroy hook wrapper
+ */
+export declare function beforeBulkDestroy(callback: BulkHookHandler): {
+    beforeBulkDestroy: BulkHookHandler;
+};
+/**
+ * Create an afterBulkDestroy hook wrapper
+ */
+export declare function afterBulkDestroy(callback: BulkHookHandler): {
+    afterBulkDestroy: BulkHookHandler;
+};
+/**
+ * Create a beforeFind hook wrapper
+ */
+export declare function beforeFind(callback: FindHookHandler): {
+    beforeFind: FindHookHandler;
+};
+/**
+ * Create an afterFind hook wrapper
+ */
+export declare function afterFind(callback: FindHookHandler): {
+    afterFind: FindHookHandler;
+};
+export default HooksManager;

package/dist/hooks/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hooks module exports for the TypeScript ORM
+ * Provides a comprehensive hooks system for model lifecycle events
+ */
+export { HooksManager, default } from './hooks-manager';
+export type { HookName, HookCallback, HooksMap, FindHookHandler, FindHookOptions, } from './hooks-manager';
+export { createHooksObject, addHookMethods, beforeValidate, afterValidate, beforeCreate, afterCreate, beforeUpdate, afterUpdate, beforeDestroy, afterDestroy, beforeSave, afterSave, beforeBulkCreate, afterBulkCreate, beforeBulkUpdate, afterBulkUpdate, beforeBulkDestroy, afterBulkDestroy, beforeFind, afterFind, } from './hooks-manager';
+export type { Model, HookOptions, HookHandler, BulkHookHandler, ModelHooks, Transaction, } from '../types';