@mostajs/orm 1.0.0

package/dist/core/types.d.ts

@@ -0,0 +1,228 @@
+export type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'array';
+export interface FieldDef {
+    type: FieldType;
+    required?: boolean;
+    unique?: boolean;
+    sparse?: boolean;
+    default?: unknown;
+    enum?: string[];
+    lowercase?: boolean;
+    trim?: boolean;
+    arrayOf?: FieldType | EmbeddedSchemaDef;
+}
+/** Embedded sub-document (e.g. Activity.schedule[], SubscriptionPlan.activities[]) */
+export interface EmbeddedSchemaDef {
+    kind: 'embedded';
+    fields: Record<string, FieldDef>;
+}
+export type RelationType = 'one-to-one' | 'many-to-one' | 'one-to-many' | 'many-to-many';
+export interface RelationDef {
+    /** Target entity name (e.g. 'User', 'Client') */
+    target: string;
+    type: RelationType;
+    required?: boolean;
+    /** Default fields to select when populating/joining */
+    select?: string[];
+    /** Whether this relation can be null */
+    nullable?: boolean;
+    /** Junction table name (SQL dialects) — convention: "{source}_{target}" in snake_case */
+    through?: string;
+}
+export type IndexType = 'asc' | 'desc' | 'text';
+export interface IndexDef {
+    fields: Record<string, IndexType>;
+    unique?: boolean;
+    sparse?: boolean;
+}
+export interface EntitySchema {
+    /** Entity name (PascalCase, e.g. 'Client') */
+    name: string;
+    /** Collection/table name (e.g. 'clients') */
+    collection: string;
+    /** Field definitions */
+    fields: Record<string, FieldDef>;
+    /** Relations to other entities */
+    relations: Record<string, RelationDef>;
+    /** Database indexes */
+    indexes: IndexDef[];
+    /** Auto-manage createdAt/updatedAt */
+    timestamps: boolean;
+}
+export interface FilterOperator {
+    $eq?: unknown;
+    $ne?: unknown;
+    $gt?: unknown;
+    $gte?: unknown;
+    $lt?: unknown;
+    $lte?: unknown;
+    $in?: unknown[];
+    $nin?: unknown[];
+    $regex?: string;
+    $regexFlags?: string;
+    $exists?: boolean;
+}
+export type FilterValue = unknown | FilterOperator;
+export interface FilterQuery {
+    [field: string]: FilterValue;
+    $or?: FilterQuery[];
+    $and?: FilterQuery[];
+}
+export type SortDirection = 1 | -1;
+export interface QueryOptions {
+    sort?: Record<string, SortDirection>;
+    skip?: number;
+    limit?: number;
+    /** Fields to include in result (projection) */
+    select?: string[];
+    /** Fields to exclude from result */
+    exclude?: string[];
+}
+export interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export interface AggregateGroupStage {
+    $group: {
+        _by: string | null;
+        [field: string]: AggregateAccumulator | string | null;
+    };
+}
+export interface AggregateAccumulator {
+    $sum?: number | string;
+    $count?: true;
+    $avg?: string;
+    $min?: string;
+    $max?: string;
+}
+export interface AggregateMatchStage {
+    $match: FilterQuery;
+}
+export interface AggregateSortStage {
+    $sort: Record<string, SortDirection>;
+}
+export interface AggregateLimitStage {
+    $limit: number;
+}
+export type AggregateStage = AggregateMatchStage | AggregateGroupStage | AggregateSortStage | AggregateLimitStage;
+export type DialectType = 'mongodb' | 'sqlite' | 'postgres' | 'mysql' | 'mariadb' | 'oracle' | 'mssql' | 'cockroachdb' | 'db2' | 'hana' | 'hsqldb' | 'spanner' | 'sybase';
+/**
+ * Schema generation strategy (inspired by hibernate.hbm2ddl.auto)
+ *
+ *   validate     : validate schema, make no changes (production)
+ *   update       : update schema to match entities (dev)
+ *   create       : drop and recreate schema on startup
+ *   create-drop  : drop schema on shutdown
+ *   none         : do nothing
+ */
+export type SchemaStrategy = 'validate' | 'update' | 'create' | 'create-drop' | 'none';
+/**
+ * Connection configuration — inspired by Hibernate persistence.xml
+ *
+ * Equivalent persistence.xml properties :
+ *   jakarta.persistence.jdbc.url     → uri
+ *   hibernate.dialect                → dialect
+ *   hibernate.show_sql               → showSql
+ *   hibernate.format_sql             → formatSql
+ *   hibernate.hbm2ddl.auto           → schemaStrategy
+ *   hibernate.connection.pool_size   → poolSize
+ *   hibernate.cache.use_second_level → cacheEnabled
+ *   hibernate.default_batch_fetch_size → batchSize
+ */
+export interface ConnectionConfig {
+    dialect: DialectType;
+    uri: string;
+    /** Log generated queries to console (default: false) */
+    showSql?: boolean;
+    /** Pretty-print logged queries (default: false) */
+    formatSql?: boolean;
+    /** Schema generation strategy (default: 'none') */
+    schemaStrategy?: SchemaStrategy;
+    /** Max connections in pool (default: dialect-specific) */
+    poolSize?: number;
+    /** Enable query result caching (default: false) */
+    cacheEnabled?: boolean;
+    /** Cache TTL in seconds (default: 60) */
+    cacheTtlSeconds?: number;
+    /** Default batch size for bulk operations (default: 25) */
+    batchSize?: number;
+    /** Additional dialect-specific options */
+    options?: Record<string, unknown>;
+}
+export interface IDialect {
+    readonly dialectType: DialectType;
+    connect(config: ConnectionConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    testConnection(): Promise<boolean>;
+    initSchema(schemas: EntitySchema[]): Promise<void>;
+    find<T = Record<string, unknown>>(schema: EntitySchema, filter: FilterQuery, options?: QueryOptions): Promise<T[]>;
+    findOne<T = Record<string, unknown>>(schema: EntitySchema, filter: FilterQuery, options?: QueryOptions): Promise<T | null>;
+    findById<T = Record<string, unknown>>(schema: EntitySchema, id: string, options?: QueryOptions): Promise<T | null>;
+    create<T = Record<string, unknown>>(schema: EntitySchema, data: Record<string, unknown>): Promise<T>;
+    update<T = Record<string, unknown>>(schema: EntitySchema, id: string, data: Record<string, unknown>): Promise<T | null>;
+    updateMany(schema: EntitySchema, filter: FilterQuery, data: Record<string, unknown>): Promise<number>;
+    delete(schema: EntitySchema, id: string): Promise<boolean>;
+    deleteMany(schema: EntitySchema, filter: FilterQuery): Promise<number>;
+    count(schema: EntitySchema, filter: FilterQuery): Promise<number>;
+    distinct(schema: EntitySchema, field: string, filter: FilterQuery): Promise<unknown[]>;
+    aggregate<T = Record<string, unknown>>(schema: EntitySchema, stages: AggregateStage[]): Promise<T[]>;
+    findWithRelations<T = Record<string, unknown>>(schema: EntitySchema, filter: FilterQuery, relations: string[], options?: QueryOptions): Promise<T[]>;
+    findByIdWithRelations<T = Record<string, unknown>>(schema: EntitySchema, id: string, relations: string[], options?: QueryOptions): Promise<T | null>;
+    upsert<T = Record<string, unknown>>(schema: EntitySchema, filter: FilterQuery, data: Record<string, unknown>): Promise<T>;
+    increment(schema: EntitySchema, id: string, field: string, amount: number): Promise<Record<string, unknown>>;
+    addToSet(schema: EntitySchema, id: string, field: string, value: unknown): Promise<Record<string, unknown> | null>;
+    pull(schema: EntitySchema, id: string, field: string, value: unknown): Promise<Record<string, unknown> | null>;
+    search<T = Record<string, unknown>>(schema: EntitySchema, query: string, fields: string[], options?: QueryOptions): Promise<T[]>;
+}
+export interface IRepository<T> {
+    findAll(filter?: FilterQuery, options?: QueryOptions): Promise<T[]>;
+    findOne(filter: FilterQuery, options?: QueryOptions): Promise<T | null>;
+    findById(id: string, options?: QueryOptions): Promise<T | null>;
+    findByIdWithRelations(id: string, relations?: string[], options?: QueryOptions): Promise<T | null>;
+    create(data: Partial<T>): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T | null>;
+    updateMany(filter: FilterQuery, data: Partial<T>): Promise<number>;
+    delete(id: string): Promise<boolean>;
+    deleteMany(filter: FilterQuery): Promise<number>;
+    count(filter?: FilterQuery): Promise<number>;
+    search(query: string, options?: QueryOptions): Promise<T[]>;
+    distinct(field: string, filter?: FilterQuery): Promise<unknown[]>;
+    aggregate<R = Record<string, unknown>>(stages: AggregateStage[]): Promise<R[]>;
+    upsert(filter: FilterQuery, data: Partial<T>): Promise<T>;
+    increment(id: string, field: string, amount: number): Promise<T | null>;
+    addToSet(id: string, field: string, value: unknown): Promise<T | null>;
+    pull(id: string, field: string, value: unknown): Promise<T | null>;
+    findWithRelations(filter: FilterQuery, relations: string[], options?: QueryOptions): Promise<T[]>;
+}
+export interface HookContext {
+    entity: EntitySchema;
+    dialect: DialectType;
+    operation: 'create' | 'update' | 'delete' | 'find';
+    userId?: string;
+}
+export interface IPlugin {
+    name: string;
+    /** Modify the schema at boot time (add fields, indexes...) */
+    onSchemaInit?(schema: EntitySchema): EntitySchema;
+    /** Before insert */
+    preSave?(doc: Record<string, unknown>, ctx: HookContext): Promise<Record<string, unknown>> | Record<string, unknown>;
+    /** After insert */
+    postSave?(doc: Record<string, unknown>, ctx: HookContext): Promise<void> | void;
+    /** Before update */
+    preUpdate?(id: string, data: Record<string, unknown>, ctx: HookContext): Promise<Record<string, unknown>> | Record<string, unknown>;
+    /** After update */
+    postUpdate?(doc: Record<string, unknown>, ctx: HookContext): Promise<void> | void;
+    /** Before delete */
+    preDelete?(id: string, ctx: HookContext): Promise<void> | void;
+    /** Transform queries (e.g. soft-delete auto-filter) */
+    onQuery?(filter: FilterQuery, ctx: HookContext): FilterQuery;
+    /** Transform results (e.g. normalization) */
+    onResult?(doc: Record<string, unknown>, ctx: HookContext): Record<string, unknown>;
+}
+/** Normalized document: id (string) instead of _id */
+export interface NormalizedDoc {
+    id: string;
+    [key: string]: unknown;
+}

package/dist/core/types.js

@@ -0,0 +1,5 @@
+// DAL Core Types - Database Abstraction Layer
+// Inspired by Hibernate ORM Dialect pattern
+// Zero dependency on any specific database driver
+// Author: Dr Hamid MADANI drmdh@msn.com
+export {};

package/dist/dialects/abstract-sql.dialect.d.ts

@@ -0,0 +1,113 @@
+import type { IDialect, DialectType, ConnectionConfig, EntitySchema, FieldDef, FilterQuery as DALFilter, QueryOptions, AggregateStage } from '../core/types.js';
+interface WhereClause {
+    sql: string;
+    params: unknown[];
+}
+export declare abstract class AbstractSqlDialect implements IDialect {
+    abstract readonly dialectType: DialectType;
+    /** Quote an identifier (column/table name) for this dialect */
+    abstract quoteIdentifier(name: string): string;
+    /** Get the parameter placeholder for index (1-based). E.g. $1, ?, :1, @p1 */
+    abstract getPlaceholder(index: number): string;
+    /** Map a DAL FieldDef to the native SQL column type */
+    abstract fieldToSqlType(field: FieldDef): string;
+    /** Get the SQL column type for the primary key (id) column */
+    abstract getIdColumnType(): string;
+    /** Execute a SELECT query, return rows */
+    abstract executeQuery<T>(sql: string, params: unknown[]): Promise<T[]>;
+    /** Execute a non-SELECT statement (INSERT/UPDATE/DELETE), return changes count */
+    abstract executeRun(sql: string, params: unknown[]): Promise<{
+        changes: number;
+    }>;
+    /** Establish the actual database connection */
+    abstract doConnect(config: ConnectionConfig): Promise<void>;
+    /** Close the actual database connection */
+    abstract doDisconnect(): Promise<void>;
+    /** Test the connection is alive */
+    abstract doTestConnection(): Promise<boolean>;
+    /** Return a SQL query that lists table names. Result rows must have a 'name' column. */
+    abstract getTableListQuery(): string;
+    protected config: ConnectionConfig | null;
+    protected schemas: EntitySchema[];
+    protected showSql: boolean;
+    protected formatSql: boolean;
+    private paramCounter;
+    /** Whether this dialect supports CREATE TABLE IF NOT EXISTS */
+    protected supportsIfNotExists(): boolean;
+    /** Whether this dialect supports RETURNING clause on INSERT */
+    protected supportsReturning(): boolean;
+    /** Serialize a JS boolean to a DB value (default: 1/0) */
+    protected serializeBoolean(v: boolean): unknown;
+    /** Deserialize a DB value to a JS boolean */
+    protected deserializeBoolean(v: unknown): boolean;
+    /** Build the LIMIT/OFFSET clause (dialect-specific override) */
+    protected buildLimitOffset(options?: QueryOptions): string;
+    /** Get the CREATE TABLE prefix, including IF NOT EXISTS when supported */
+    protected getCreateTablePrefix(tableName: string): string;
+    /** Get the CREATE INDEX prefix, including IF NOT EXISTS when supported */
+    protected getCreateIndexPrefix(indexName: string, unique: boolean): string;
+    /** Serialize date values to a format suitable for this dialect */
+    protected serializeDate(value: unknown): unknown;
+    /** Serialize JSON/array values */
+    protected serializeJson(value: unknown): unknown;
+    /**
+     * Build a regex/LIKE condition. Override for case-sensitive dialects.
+     * Default: LIKE (case-insensitive in MySQL, SQLite, MSSQL; case-sensitive in Postgres, Oracle, DB2, HANA).
+     * Postgres overrides to use ILIKE when flags contain 'i'.
+     */
+    protected buildRegexCondition(col: string, flags?: string): string;
+    /** Dialect label for logging */
+    protected getDialectLabel(): string;
+    protected log(operation: string, table: string, details?: unknown): void;
+    /** Reset the parameter counter (call before building a new statement) */
+    protected resetParams(): void;
+    /** Get the next placeholder and increment the counter */
+    protected nextPlaceholder(): string;
+    protected serializeValue(value: unknown, field?: FieldDef): unknown;
+    protected deserializeRow(row: Record<string, unknown>, schema: EntitySchema): Record<string, unknown>;
+    protected deserializeField(val: unknown, field: FieldDef): unknown;
+    protected translateFilter(filter: DALFilter, schema: EntitySchema): WhereClause;
+    protected serializeForFilter(value: unknown, fieldName: string, schema: EntitySchema): unknown;
+    protected buildSelectColumns(schema: EntitySchema, options?: QueryOptions): string;
+    protected getAllColumns(schema: EntitySchema): string[];
+    protected buildOrderBy(options?: QueryOptions): string;
+    protected prepareInsertData(schema: EntitySchema, data: Record<string, unknown>): {
+        columns: string[];
+        placeholders: string[];
+        values: unknown[];
+    };
+    protected prepareUpdateData(schema: EntitySchema, data: Record<string, unknown>): {
+        setClauses: string[];
+        values: unknown[];
+    };
+    protected generateCreateTable(schema: EntitySchema): string;
+    protected generateIndexes(schema: EntitySchema): string[];
+    connect(config: ConnectionConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    testConnection(): Promise<boolean>;
+    initSchema(schemas: EntitySchema[]): Promise<void>;
+    find<T>(schema: EntitySchema, filter: DALFilter, options?: QueryOptions): Promise<T[]>;
+    findOne<T>(schema: EntitySchema, filter: DALFilter, options?: QueryOptions): Promise<T | null>;
+    findById<T>(schema: EntitySchema, id: string, options?: QueryOptions): Promise<T | null>;
+    create<T>(schema: EntitySchema, data: Record<string, unknown>): Promise<T>;
+    update<T>(schema: EntitySchema, id: string, data: Record<string, unknown>): Promise<T | null>;
+    updateMany(schema: EntitySchema, filter: DALFilter, data: Record<string, unknown>): Promise<number>;
+    delete(schema: EntitySchema, id: string): Promise<boolean>;
+    deleteMany(schema: EntitySchema, filter: DALFilter): Promise<number>;
+    count(schema: EntitySchema, filter: DALFilter): Promise<number>;
+    distinct(schema: EntitySchema, field: string, filter: DALFilter): Promise<unknown[]>;
+    aggregate<T>(schema: EntitySchema, stages: AggregateStage[]): Promise<T[]>;
+    findWithRelations<T>(schema: EntitySchema, filter: DALFilter, relations: string[], options?: QueryOptions): Promise<T[]>;
+    findByIdWithRelations<T>(schema: EntitySchema, id: string, relations: string[], options?: QueryOptions): Promise<T | null>;
+    private populateRelations;
+    upsert<T>(schema: EntitySchema, filter: DALFilter, data: Record<string, unknown>): Promise<T>;
+    increment(schema: EntitySchema, id: string, field: string, amount: number): Promise<Record<string, unknown>>;
+    addToSet(schema: EntitySchema, id: string, field: string, value: unknown): Promise<Record<string, unknown> | null>;
+    pull(schema: EntitySchema, id: string, field: string, value: unknown): Promise<Record<string, unknown> | null>;
+    search<T>(schema: EntitySchema, query: string, fields: string[], options?: QueryOptions): Promise<T[]>;
+    /** Check if a table exists */
+    protected tableExists(tableName: string): Promise<boolean>;
+    /** Drop all tables (used by 'create' and 'create-drop' strategies) */
+    protected dropAllTables(): Promise<void>;
+}
+export {};