ts-prorm-orm 1.1.0 → 1.2.1

package/dist/models/model.js

@@ -39,6 +39,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelValidator = exports.ModelInstance = exports.Model = void 0;
 exports.createModel = createModel;
+const eager_load_1 = require("./eager-load");
 const operators_1 = require("./operators");
 const scopes_1 = require("./scopes");
 const associations_1 = require("./associations");
@@ -233,112 +234,25 @@ function resolveDuplicateColumns(includes, parentModel, parentAlias) {
     };
 }
 /**
- * Process nested includes and attach associated records to parent instances
- * This performs additional queries for nested associations not handled by JOINs
+ * Process nested includes and attach associated records to parent instances.
+ *
+ * Delegates to the shared eager-loader in `./eager-load`. This function used to
+ * carry its own implementation, which handled `belongsTo` exactly like `hasMany`
+ * (querying the target table for a foreign key that actually lives on the
+ * parent) and skipped `belongsToMany` with a bare `continue`. Models defined via
+ * `prorm.define()` went through a separate, differently-buggy copy in prorm.ts;
+ * both now share one implementation.
  */
 async function processNestedIncludes(instances, includes, prorm, parentModel) {
     if (!instances.length || !includes.length) {
         return;
     }
-    for (const include of includes) {
-        const model = include.model;
-        const as = include.as || model.tableName || model.name;
-        // Get the parent model's association for this include
-        // First try by the 'as' alias, then by model name
-        let association = parentModel.associations?.[as];
-        if (!association) {
-            // Try to find by model name
-            for (const [, assoc] of Object.entries(parentModel.associations || {})) {
-                const target = assoc.target;
-                if (target === model || target.name === model.name) {
-                    association = assoc;
-                    break;
-                }
-            }
-        }
-        if (!association) {
-            throw new Error(`Invalid include: '${as}' is not an association of ${parentModel.name}`);
-        }
-        // Get primary key values from parent instances
-        const pkField = getPrimaryKeyField(parentModel);
-        const parentIds = instances
-            .map((instance) => instance.getDataValue(pkField))
-            .filter((id) => id !== undefined && id !== null);
-        if (!parentIds.length) {
-            continue;
-        }
-        // Build where clause based on association type
-        let whereClause = {};
-        let foreignKey = '';
-        if (association.type === 'belongsTo') {
-            // For belongsTo, the foreign key is on the parent
-            foreignKey = association.foreignKey;
-            whereClause = { [foreignKey]: { $in: parentIds } };
-        }
-        else if (association.type === 'hasMany' || association.type === 'hasOne') {
-            // For hasMany/hasOne, the foreign key is on the target model
-            foreignKey = association.foreignKey;
-            whereClause = { [foreignKey]: { $in: parentIds } };
-        }
-        else if (association.type === 'belongsToMany') {
-            // For belongsToMany, we need to go through the junction table
-            continue;
-        }
-        // Apply additional where conditions from include
-        if (include.where) {
-            whereClause = { ...whereClause, ...include.where };
-        }
-        // Build query options for the associated model
-        const queryOptions = {
-            where: whereClause,
-            attributes: include.attributes,
-            order: include.order,
-            limit: include.limit,
-            offset: include.offset,
-        };
-        // Fetch associated records
-        const associatedRecords = await model.findAll(queryOptions);
-        // Group associated records by foreign key value
-        const groupedRecords = new Map();
-        for (const record of associatedRecords) {
-            const fkValue = record.getDataValue(foreignKey);
-            if (!groupedRecords.has(fkValue)) {
-                groupedRecords.set(fkValue, []);
-            }
-            groupedRecords.get(fkValue).push(record);
-        }
-        // Attach associated records to parent instances
-        for (const instance of instances) {
-            const pkValue = instance.getDataValue(pkField);
-            const related = groupedRecords.get(pkValue);
-            if (related) {
-                // Set based on association type (hasMany returns array, hasOne returns single)
-                if (association.type === 'hasMany') {
-                    instance.setDataValue(as, related);
-                }
-                else {
-                    instance.setDataValue(as, related[0] || null);
-                }
-            }
-            else {
-                // Set empty value if no related records
-                if (association.type === 'hasMany') {
-                    instance.setDataValue(as, []);
-                }
-                else {
-                    instance.setDataValue(as, null);
-                }
-            }
-        }
-        // Recursively process nested includes
-        if (include.include && include.include.length > 0) {
-            // Get all unique associated records
-            const allAssociated = Array.from(groupedRecords.values()).flat();
-            if (allAssociated.length > 0) {
-                await processNestedIncludes(allAssociated, include.include, prorm, model);
-            }
-        }
-    }
+    await (0, eager_load_1.loadIncludes)({
+        // Array, not the Map iterator - the loader rescans this for every
+        // include and every nested level.
+        associations: Array.from(prorm.associations.values()),
+        models: prorm._models ?? prorm.models ?? {},
+    }, instances, parentModel, parentModel.name, includes);
 }
 /**
  * Get the primary key field name for a model

package/dist/models/operators.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Operator symbols for the ORM
+ * Provides all Prorm operators for query building
+ * This file re-exports from the main operators.ts for consistency
+ *
+ * Usage Examples:
+ * ```typescript
+ * import { Op, and, or, eq, gte } from 'orm';
+ *
+ * // Using Op directly (recommended)
+ * User.findAll({ where: { age: { [Op.gte]: 18 } } })
+ * User.findAll({ where: { name: { [Op.like]: '%john%' } } })
+ *
+ * // Using helper functions
+ * User.findAll({ where: and({ name: 'John' }, { age: gte('age', 18) }) })
+ *
+ * // Column comparison
+ * User.findAll({ where: { balance: { [Op.eq]: Op.col('credit_limit') } } })
+ *
+ * // JSON column queries
+ * User.findAll({ where: { settings: Op.json({ theme: 'dark' }) } })
+ * ```
+ */
+export { and, or, not, eq, ne, gt, gte, lt, lte, like, notLike, inOp as in, notIn, between, notBetween, isNull, isNotNull, where, operatorToWhereKey, isOperator, iLike, notILike, regexp, notRegexp, iRegexp, notIRegexp, contains, overlap, cast, Cast, asc, desc, random, isOrderExpression, } from '../operators';
+export type { OperatorSymbol, WhereConditionOptions, OpType, OrderExpression, FnExpression, CastExpression, ExtractExpression, ConvExpression, } from '../operators';
+import { Op } from '../operators';
+export { Op };
+export { Op as default };
+export type Operator = symbol;

package/dist/models/scopes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Scope management for the ORM
+ * Provides defaultScope, named scopes, and scoped model access
+ */
+import { ModelStatic, Model, ScopeOptions, FindOptions } from '../types';
+/**
+ * Scope manager for model scoping
+ */
+export declare class ScopeManager {
+    private scopes;
+    private defaultScope;
+    private model;
+    private _currentScope;
+    constructor(model: ModelStatic<Model>);
+    /**
+     * Add a named scope
+     */
+    addScope(name: string, options: ScopeOptions): void;
+    /**
+     * Set the default scope
+     */
+    setDefaultScope(options: ScopeOptions): void;
+    /**
+     * Get a scope by name
+     */
+    getScope(name: string): ScopeOptions | undefined;
+    /**
+     * Check if a scope exists
+     */
+    hasScope(name: string): boolean;
+    /**
+     * Remove a scope by name
+     */
+    removeScope(name: string): boolean;
+    /**
+     * Clear all named scopes
+     */
+    clearScopes(): void;
+    /**
+     * Get the count of defined scopes
+     */
+    getScopeCount(): number;
+    /**
+     * Get all defined scopes
+     */
+    getAllScopes(): Map<string, ScopeOptions>;
+    /**
+     * Get the default scope
+     */
+    getDefaultScope(): ScopeOptions | null;
+    /**
+     * Apply a scope to options
+     */
+    applyScope(scopeName: string, options?: FindOptions): FindOptions;
+    /**
+     * Get the current active scope name
+     */
+    getCurrentScope(): string | null;
+    /**
+     * Clear the current scope
+     */
+    clearScope(): void;
+    /**
+     * Merge scope options with query options
+     */
+    mergeScopeOptions(options: FindOptions, scope: ScopeOptions): FindOptions;
+    /**
+     * Merge where conditions
+     */
+    private mergeWhere;
+}

package/dist/models/typescript-types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * TypeScript Type Utilities for Model Definitions
+ *
+ * This module provides TypeScript type utilities:
+ * - InferAttributes<T>: Extracts attribute types from a Model
+ * - InferCreationAttributes<T>: Extracts creation attributes (with optional ID, etc.)
+ * - CreationOptional<T>: Marks an attribute as optional during creation
+ * - NonAttribute<T>: Excludes non-database fields (methods, getters)
+ * - ForeignKey<T, TModel>: Branded type for foreign key relationships
+ *
+ * @example
+ * ```typescript
+ * import { Model, InferAttributes, InferCreationAttributes, CreationOptional } from 'orm';
+ *
+ * export class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
+ *   declare id: CreationOptional<number>;
+ *   declare name: string;
+ *   declare email: string;
+ *
+ *   // Non-database property
+ *   declare getFullName(): NonAttribute<string>;
+ * }
+ * ```
+ */
+import type { IndexOptions } from '../dialects/dialect';
+/**
+ * Marks an attribute as optional when creating a model instance.
+ * Used for auto-incrementing IDs, default values, etc.
+ *
+ * @example
+ * declare id: CreationOptional<number>;
+ * declare createdAt: CreationOptional<Date>;
+ */
+export type CreationOptional<T> = T | undefined;
+/**
+ * Excludes a property from being treated as a database attribute.
+ * Use for instance methods, getters, setters, and non-persisted properties.
+ *
+ * @example
+ * declare fullName: NonAttribute<string>;
+ * declare getFullName(): NonAttribute<string>;
+ */
+export type NonAttribute<T> = T;
+/**
+ * Branded type for foreign key relationships.
+ * Provides type safety when defining associations.
+ *
+ * @example
+ * declare userId: ForeignKey<User['id']>;
+ */
+export interface ForeignKey<T> {
+    __brand: 'ForeignKey';
+    value: T;
+}
+/**
+ * PartialBy - Constructs a type with all properties of T except those in K set to optional.
+ *
+ * @example
+ * type UserCreationAttributes = PartialBy<UserAttributes, 'id'>;
+ * // { id?: number, name: string, email: string }
+ */
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * RequiredBy - Constructs a type with all properties of T having the opposite optionality of K.
+ *
+ * @example
+ * type RequiredUser = RequiredBy<UserAttributes, 'name'>;
+ * // { id: number, name: string, email?: string }
+ */
+export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * InferAttributes - Extracts attribute types from a Model
+ *
+ * Use this type to extract the attribute types when defining a Model class.
+ * This type should be used as the first type parameter to Model.
+ *
+ * @example
+ * export class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
+ *   declare id: CreationOptional<number>;
+ *   declare name: string;
+ * }
+ */
+export type InferAttributes<T> = {
+    [K in keyof T]: T[K] extends NonAttribute<any> ? never : T[K];
+};
+/**
+ * InferCreationAttributes - Extracts creation attribute types from a Model
+ *
+ * Use this type to extract the attribute types that can be used when creating
+ * a model instance. By default, all attributes are optional since creation
+ * may only require a subset.
+ *
+ * @example
+ * export class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
+ *   declare id: CreationOptional<number>;
+ *   declare name: string;
+ * }
+ */
+export type InferCreationAttributes<T> = {
+    [K in keyof T]: T[K] extends NonAttribute<any> ? never : T[K] extends CreationOptional<infer U> ? U | undefined : T[K];
+};
+/**
+ * Model static type with all required properties
+ */
+export interface ModelStatic<T = any> {
+    /** Model name */
+    name: string;
+    /** Table name */
+    tableName?: string;
+    /** Schema (if applicable) */
+    schema?: string;
+    /** Primary key attribute name */
+    primaryKeyAttribute?: string;
+    /** Unique attributes */
+    uniqueKeys?: Record<string, string[]>;
+    /** Attributes definition */
+    attributes: Record<string, any>;
+    /** Associations */
+    associations: Record<string, any>;
+    /** Options */
+    options: ModelOptions;
+    /** Get the table name */
+    getTableName(): string;
+    /** Get the attribute names */
+    getAttributes(): string[];
+    /** Get the primary key attribute */
+    getPrimaryKeyAttribute(): string | undefined;
+}
+/**
+ * Model options type
+ */
+export interface ModelOptions {
+    /** Table name */
+    tableName?: string;
+    /** Schema name */
+    schema?: string;
+    /** Schema delimiter */
+    schemaDelimiter?: string;
+    /** Engine (for MySQL) */
+    engine?: string;
+    /** Model name */
+    modelName?: string;
+    /** Enable hooks */
+    hooks?: boolean;
+    /** Override default timestamp columns */
+    underscored?: boolean;
+    /** Use pluralized table name */
+    freezeTableName?: boolean;
+    /** Indexes */
+    indexes?: IndexOptions[];
+    /** Comment */
+    comment?: string;
+    /** Default collation (MySQL) */
+    collate?: string;
+    /** Validation */
+    validate?: Record<string, any>;
+    /** Timestamps */
+    timestamps?: boolean;
+    /** CreatedAt column name */
+    createdAt?: string | false;
+    /** UpdatedAt column name */
+    updatedAt?: string | false;
+    /** DeletedAt column name (paranoid) */
+    deletedAt?: string | false;
+    /** Primary key option */
+    primaryKey?: boolean;
+    /** Column names */
+    columnNames?: Record<string, string>;
+}
+/**
+ * Type for belongsTo association target
+ */
+export type BelongsToManyTarget<T> = T;
+/**
+ * Type for foreign key attribute
+ */
+export type ForeignKeyAttribute<T extends number | string = number> = T;

package/dist/nosql/aerospike/index.d.ts

@@ -0,0 +1,126 @@
+import type { NoSqlStore } from '../store';
+/** A single Aerospike host descriptor (`{ addr, port }`), matching the driver's config shape. */
+export interface AerospikeHost {
+    addr: string;
+    port?: number;
+}
+/**
+ * A key may be given as a bare string/number (resolved against the store's
+ * default `namespace`/`set`), or as an explicit `(namespace, set, key)` tuple
+ * that overrides either of those per call.
+ */
+export type AerospikeKeyInput = string | number | {
+    namespace?: string;
+    set?: string;
+    key: string | number;
+};
+/** The `(namespace, set, key)` tuple used to address a record, as built by `makeKey()`. */
+export interface AerospikeKeyTuple {
+    ns: string;
+    set: string;
+    key: string | number;
+}
+/** Optional per-record write metadata (TTL, generation) forwarded to `put()`. */
+export interface AerospikeMeta {
+    /** Time-to-live in seconds. */
+    ttl?: number;
+    /** Expected record generation, for optimistic-concurrency writes. */
+    gen?: number;
+    [key: string]: unknown;
+}
+/**
+ * Minimal structural type for the pieces of an `aerospike` client this store
+ * uses. Kept local (rather than importing from `aerospike`) so this module
+ * type-checks without the optional driver installed.
+ */
+export interface AerospikeClientLike {
+    put(key: unknown, bins: Record<string, unknown>, meta?: unknown): Promise<unknown>;
+    get(key: unknown): Promise<{
+        bins: Record<string, unknown>;
+    }>;
+    remove(key: unknown): Promise<unknown>;
+    exists(key: unknown): Promise<boolean>;
+    operate(key: unknown, ops: unknown[]): Promise<unknown>;
+    truncate?(namespace: string, set: string | null, beforeNanos: number): Promise<unknown>;
+    close(release?: boolean): void;
+}
+/** Connection options for `AerospikeStore`. */
+export interface AerospikeStoreOptions {
+    /** One or more Aerospike hosts, e.g. `[{ addr: '127.0.0.1', port: 3000 }]`. */
+    hosts?: AerospikeHost[];
+    /** Default namespace applied to keys that don't specify one. */
+    namespace?: string;
+    /** Default set applied to keys that don't specify one. Defaults to `''`. */
+    set?: string;
+    /**
+     * Escape hatch for any other `aerospike` config field (policies, auth,
+     * TLS, ...). Merged into the config passed to `Aerospike.connect()`.
+     */
+    config?: Record<string, unknown>;
+    /**
+     * A pre-built `aerospike` client (or a compatible mock). When provided,
+     * `connect()` uses it directly and skips `require('aerospike')` entirely —
+     * this is how tests inject a mock without the real driver installed.
+     */
+    client?: AerospikeClientLike;
+}
+/**
+ * `AerospikeStore` wraps an `aerospike` client and exposes Aerospike's record
+ * surface: `put`/`get`/`remove`/`exists` for single-record operations,
+ * `operate` for atomic multi-op transactions on a record, and `truncate` for
+ * clearing a set. Records are addressed by a `(namespace, set, key)` tuple,
+ * built by `makeKey()`.
+ */
+export declare class AerospikeStore implements NoSqlStore {
+    readonly name = "aerospike";
+    readonly library = "aerospike";
+    private readonly options;
+    private readonly namespace;
+    private readonly set;
+    private client;
+    private connected;
+    /**
+     * The required `aerospike` module, kept so `makeKey()` can build a real
+     * `Aerospike.Key`. Stays `null` when a client is injected (tests), in which
+     * case `makeKey()` returns a plain `{ ns, set, key }` tuple instead.
+     */
+    private aerospike;
+    constructor(options?: AerospikeStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `aerospike` client for anything not wrapped here. */
+    getClient(): AerospikeClientLike;
+    private requireClient;
+    private wrapError;
+    /**
+     * Builds the key object the driver expects from a `(namespace, set, key)`
+     * tuple, filling in the store's default namespace/set for anything the
+     * caller omits. When the real driver is loaded this returns a
+     * `new Aerospike.Key(namespace, set, key)`; when a mock client is injected
+     * (no module) it returns a plain `{ ns, set, key }` tuple.
+     */
+    makeKey(input: AerospikeKeyInput): AerospikeKeyTuple | unknown;
+    /** Writes (puts) a record's bins. Optionally accepts write metadata (TTL/generation). */
+    put(key: AerospikeKeyInput, bins: Record<string, unknown>, meta?: AerospikeMeta): Promise<unknown>;
+    /** Reads a record by key, returning its bins (`record.bins`), or throws if it doesn't exist. */
+    get(key: AerospikeKeyInput): Promise<Record<string, unknown>>;
+    /** Removes a record by key. */
+    remove(key: AerospikeKeyInput): Promise<unknown>;
+    /** Returns whether a record exists for the given key. */
+    exists(key: AerospikeKeyInput): Promise<boolean>;
+    /**
+     * Runs an ordered list of operations atomically against a single record
+     * (Aerospike's `operate` — increment, append, read-back, etc). `ops` is
+     * passed straight through to the driver; build them with the driver's own
+     * operation helpers.
+     */
+    operate(key: AerospikeKeyInput, ops: unknown[]): Promise<unknown>;
+    /**
+     * Truncates a set (or the store's default set), deleting every record in it.
+     * `beforeNanos` of `0` means "everything up to now". Requires a driver whose
+     * client exposes `truncate()`.
+     */
+    truncate(set?: string): Promise<unknown>;
+}
+export default AerospikeStore;

package/dist/nosql/allegrograph/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * AllegroGraph store implementation.
+ *
+ * AllegroGraph is a semantic-graph / RDF triplestore. Its repositories are
+ * queried over the SPARQL 1.1 Protocol via a per-repository HTTP endpoint
+ * (`/repositories/<repo>`) used for both queries and updates. There is no
+ * SQL-shaped surface, so it implements the minimal `NoSqlStore` marker
+ * interface (`src/nosql/store.ts`) rather than the SQL `Dialect` interface.
+ *
+ * ## Driver strategy - prefer HTTP over `fetch`
+ *
+ * AllegroGraph ships an `agraph-js` client, but this store prefers the plain
+ * SPARQL/HTTP protocol over the global `fetch` so it has no hard dependency
+ * (`library='fetch'`). For tests (and for callers who want their own
+ * transport) an alternative client can be injected via
+ * `AllegrographStoreOptions.client`; when omitted, a tiny internal client over
+ * `fetch` + `endpoint` is built at connect time.
+ *
+ * ## Surface
+ *
+ * - `query(sparql)`  -> POST to `/repositories/<repo>`, returns bindings
+ * - `update(sparql)` -> POST to `/repositories/<repo>`
+ * - `ask(sparql)`    -> POST an ASK query, returns the boolean
+ * - `add(triples)`   -> `INSERT DATA { ... }` update
+ * - `drop(graph?)`   -> `DROP GRAPH <g>` / `DROP ALL` update
+ */
+import { NoSqlStore } from '../store';
+/** Default AllegroGraph base URL. */
+export declare const DEFAULT_ALLEGROGRAPH_ENDPOINT = "http://localhost:10035";
+/** Default repository id. */
+export declare const DEFAULT_ALLEGROGRAPH_REPOSITORY = "repo";
+/** The subset of a SPARQL HTTP client this store needs. */
+export interface SparqlHttpClient {
+    /** POST a SPARQL query to `path`; returns the parsed results envelope. */
+    query(path: string, sparql: string): Promise<any>;
+    /** POST a SPARQL update to `path`. */
+    update(path: string, sparql: string): Promise<any>;
+}
+/** Connection options for `AllegrographStore`. */
+export interface AllegrographStoreOptions {
+    /** Base URL of the AllegroGraph server. Defaults to `http://localhost:10035`. */
+    endpoint?: string;
+    /** Repository id. Defaults to `repo`. */
+    repository?: string;
+    /** Optional pre-built SPARQL HTTP client (used verbatim; `endpoint` ignored). */
+    client?: SparqlHttpClient;
+    /** Extra HTTP headers sent with every internal-client request. */
+    headers?: Record<string, string>;
+}
+/** Build a `fetch`-backed SPARQL client for the given endpoint. */
+export declare function createFetchClient(endpoint: string, headers?: Record<string, string>): SparqlHttpClient;
+/**
+ * `AllegrographStore` wraps an AllegroGraph repository's SPARQL endpoint behind
+ * the `NoSqlStore` lifecycle.
+ */
+export declare class AllegrographStore implements NoSqlStore {
+    readonly name = "allegrograph";
+    readonly library = "fetch";
+    private readonly endpoint;
+    private readonly repository;
+    private readonly injectedClient?;
+    private readonly headers?;
+    private client;
+    private connected;
+    constructor(options?: AllegrographStoreOptions);
+    /** SPARQL query endpoint path for the configured repository. */
+    get queryPath(): string;
+    /** SPARQL update endpoint path for the configured repository (same endpoint). */
+    get updatePath(): string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying (internal or injected) SPARQL HTTP client. */
+    getClient(): SparqlHttpClient;
+    private requireClient;
+    /** Runs a SPARQL SELECT/CONSTRUCT query; returns the result bindings. */
+    query(sparql: string): Promise<any[]>;
+    /** Runs a SPARQL ASK query; returns the boolean answer. */
+    ask(sparql: string): Promise<boolean>;
+    /** Runs a SPARQL UPDATE (INSERT/DELETE/DROP/...). */
+    update(sparql: string): Promise<any>;
+    /** Inserts triples via `INSERT DATA { ... }`. Accepts a triple string or array. */
+    add(triples: string | string[], graph?: string): Promise<any>;
+    /** Drops a named graph, or all graphs when no graph is given. */
+    drop(graph?: string): Promise<any>;
+}