@mostajs/orm 1.0.0

package/dist/core/config.d.ts

@@ -0,0 +1,62 @@
+import type { DialectType } from './types.js';
+export interface DialectConfig {
+    /** npm install command for the driver */
+    installHint: string;
+    /** Human-readable label */
+    label: string;
+}
+/**
+ * Dialect metadata registry.
+ * Connection config (dialect + URI) comes from .env.local, NOT from here.
+ *
+ * .env.local format (decommenter UN bloc) :
+ *
+ *   DB_DIALECT=mongodb
+ *   SGBD_URI=mongodb://user:pass@localhost:27017/mydb
+ *
+ *   #DB_DIALECT=sqlite
+ *   #SGBD_URI=./data/myapp.db
+ *
+ *   #DB_DIALECT=postgres
+ *   #SGBD_URI=postgresql://user:pass@localhost:5432/mydb
+ *
+ *   #DB_DIALECT=mysql
+ *   #SGBD_URI=mysql://user:pass@localhost:3306/mydb
+ *
+ *   #DB_DIALECT=mariadb
+ *   #SGBD_URI=mariadb://user:pass@localhost:3306/mydb
+ *
+ *   #DB_DIALECT=oracle
+ *   #SGBD_URI=oracle://user:pass@localhost:1521/mydb
+ *
+ *   #DB_DIALECT=mssql
+ *   #SGBD_URI=mssql://user:pass@localhost:1433/mydb
+ *
+ *   #DB_DIALECT=cockroachdb
+ *   #SGBD_URI=postgresql://user:pass@localhost:26257/mydb
+ *
+ *   #DB_DIALECT=db2
+ *   #SGBD_URI=db2://user:pass@localhost:50000/mydb
+ *
+ *   #DB_DIALECT=hana
+ *   #SGBD_URI=hana://user:pass@localhost:30015
+ *
+ *   #DB_DIALECT=hsqldb
+ *   #SGBD_URI=hsqldb:hsql://localhost:9001/mydb
+ *
+ *   #DB_DIALECT=spanner
+ *   #SGBD_URI=spanner://project/instance/mydb
+ *
+ *   #DB_DIALECT=sybase
+ *   #SGBD_URI=sybase://user:pass@localhost:5000/mydb
+ */
+export declare const DIALECT_CONFIGS: Record<DialectType, DialectConfig>;
+/**
+ * Get the list of supported dialect types
+ */
+export declare function getSupportedDialects(): DialectType[];
+/**
+ * Get metadata for a specific dialect.
+ * Throws if the dialect is not supported.
+ */
+export declare function getDialectConfig(dialect: DialectType): DialectConfig;

package/dist/core/config.js

@@ -0,0 +1,116 @@
+/**
+ * Dialect metadata registry.
+ * Connection config (dialect + URI) comes from .env.local, NOT from here.
+ *
+ * .env.local format (decommenter UN bloc) :
+ *
+ *   DB_DIALECT=mongodb
+ *   SGBD_URI=mongodb://user:pass@localhost:27017/mydb
+ *
+ *   #DB_DIALECT=sqlite
+ *   #SGBD_URI=./data/myapp.db
+ *
+ *   #DB_DIALECT=postgres
+ *   #SGBD_URI=postgresql://user:pass@localhost:5432/mydb
+ *
+ *   #DB_DIALECT=mysql
+ *   #SGBD_URI=mysql://user:pass@localhost:3306/mydb
+ *
+ *   #DB_DIALECT=mariadb
+ *   #SGBD_URI=mariadb://user:pass@localhost:3306/mydb
+ *
+ *   #DB_DIALECT=oracle
+ *   #SGBD_URI=oracle://user:pass@localhost:1521/mydb
+ *
+ *   #DB_DIALECT=mssql
+ *   #SGBD_URI=mssql://user:pass@localhost:1433/mydb
+ *
+ *   #DB_DIALECT=cockroachdb
+ *   #SGBD_URI=postgresql://user:pass@localhost:26257/mydb
+ *
+ *   #DB_DIALECT=db2
+ *   #SGBD_URI=db2://user:pass@localhost:50000/mydb
+ *
+ *   #DB_DIALECT=hana
+ *   #SGBD_URI=hana://user:pass@localhost:30015
+ *
+ *   #DB_DIALECT=hsqldb
+ *   #SGBD_URI=hsqldb:hsql://localhost:9001/mydb
+ *
+ *   #DB_DIALECT=spanner
+ *   #SGBD_URI=spanner://project/instance/mydb
+ *
+ *   #DB_DIALECT=sybase
+ *   #SGBD_URI=sybase://user:pass@localhost:5000/mydb
+ */
+export const DIALECT_CONFIGS = {
+    mongodb: {
+        installHint: 'npm install mongoose',
+        label: 'MongoDB',
+    },
+    sqlite: {
+        installHint: 'npm install better-sqlite3',
+        label: 'SQLite',
+    },
+    postgres: {
+        installHint: 'npm install pg',
+        label: 'PostgreSQL',
+    },
+    mysql: {
+        installHint: 'npm install mysql2',
+        label: 'MySQL',
+    },
+    mariadb: {
+        installHint: 'npm install mariadb',
+        label: 'MariaDB',
+    },
+    oracle: {
+        installHint: 'npm install oracledb',
+        label: 'Oracle Database',
+    },
+    mssql: {
+        installHint: 'npm install mssql',
+        label: 'SQL Server',
+    },
+    cockroachdb: {
+        installHint: 'npm install pg',
+        label: 'CockroachDB',
+    },
+    db2: {
+        installHint: 'npm install ibm_db',
+        label: 'IBM DB2',
+    },
+    hana: {
+        installHint: 'npm install @sap/hana-client',
+        label: 'SAP HANA',
+    },
+    hsqldb: {
+        installHint: 'npm install hsqldb (Java driver)',
+        label: 'HyperSQL',
+    },
+    spanner: {
+        installHint: 'npm install @google-cloud/spanner',
+        label: 'Google Cloud Spanner',
+    },
+    sybase: {
+        installHint: 'npm install sybase',
+        label: 'Sybase ASE',
+    },
+};
+/**
+ * Get the list of supported dialect types
+ */
+export function getSupportedDialects() {
+    return Object.keys(DIALECT_CONFIGS);
+}
+/**
+ * Get metadata for a specific dialect.
+ * Throws if the dialect is not supported.
+ */
+export function getDialectConfig(dialect) {
+    const config = DIALECT_CONFIGS[dialect];
+    if (!config) {
+        throw new Error(`Unknown dialect "${dialect}". Supported: ${getSupportedDialects().join(', ')}`);
+    }
+    return config;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Base error class for all MostaORM errors
+ */
+export declare class MostaORMError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when an entity is not found by ID or filter
+ */
+export declare class EntityNotFoundError extends MostaORMError {
+    constructor(entityName: string, id?: string);
+}
+/**
+ * Thrown when a database connection fails
+ */
+export declare class ConnectionError extends MostaORMError {
+    constructor(dialect: string, cause?: string);
+}
+/**
+ * Thrown when entity data fails validation
+ */
+export declare class ValidationError extends MostaORMError {
+    constructor(entityName: string, details: string);
+}
+/**
+ * Thrown when a dialect is not found or not supported
+ */
+export declare class DialectNotFoundError extends MostaORMError {
+    constructor(dialect: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,49 @@
+// MostaORM Error Classes
+// Author: Dr Hamid MADANI drmdh@msn.com
+/**
+ * Base error class for all MostaORM errors
+ */
+export class MostaORMError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MostaORMError';
+    }
+}
+/**
+ * Thrown when an entity is not found by ID or filter
+ */
+export class EntityNotFoundError extends MostaORMError {
+    constructor(entityName, id) {
+        super(id
+            ? `${entityName} with id "${id}" not found`
+            : `${entityName} not found`);
+        this.name = 'EntityNotFoundError';
+    }
+}
+/**
+ * Thrown when a database connection fails
+ */
+export class ConnectionError extends MostaORMError {
+    constructor(dialect, cause) {
+        super(`Failed to connect to ${dialect}${cause ? `: ${cause}` : ''}`);
+        this.name = 'ConnectionError';
+    }
+}
+/**
+ * Thrown when entity data fails validation
+ */
+export class ValidationError extends MostaORMError {
+    constructor(entityName, details) {
+        super(`Validation failed for ${entityName}: ${details}`);
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Thrown when a dialect is not found or not supported
+ */
+export class DialectNotFoundError extends MostaORMError {
+    constructor(dialect) {
+        super(`Dialect "${dialect}" is not supported`);
+        this.name = 'DialectNotFoundError';
+    }
+}

package/dist/core/factory.d.ts

@@ -0,0 +1,41 @@
+import type { IDialect, DialectType, ConnectionConfig, EntitySchema } from './types.js';
+/**
+ * Read the database configuration from environment variables.
+ *
+ * Required env vars:
+ *   DB_DIALECT  = mongodb | sqlite | postgres | mysql | mariadb | oracle | mssql | cockroachdb | db2 | hana | hsqldb | spanner | sybase
+ *   SGBD_URI    = connection string
+ *
+ * Throws if DB_DIALECT or SGBD_URI is missing.
+ */
+export declare function getConfigFromEnv(): ConnectionConfig;
+/**
+ * Initialize and connect the dialect.
+ * Returns a singleton — subsequent calls return the same instance.
+ */
+export declare function getDialect(config?: ConnectionConfig): Promise<IDialect>;
+/**
+ * Get the current dialect type without connecting.
+ */
+export declare function getCurrentDialectType(): DialectType;
+/**
+ * Disconnect the current dialect and reset the singleton.
+ */
+export declare function disconnectDialect(): Promise<void>;
+/**
+ * Test the connection with a given config without changing the active dialect.
+ * Used by the setup wizard to validate before committing.
+ */
+export declare function testConnection(config: ConnectionConfig): Promise<boolean>;
+/**
+ * Simplified high-level API: connect to a database and optionally register schemas.
+ * Returns the connected dialect instance.
+ *
+ * Example:
+ *   const dialect = await createConnection({
+ *     dialect: 'sqlite',
+ *     uri: './my.db',
+ *     schemaStrategy: 'update',
+ *   }, [ContactSchema, OrderSchema]);
+ */
+export declare function createConnection(config: ConnectionConfig, schemas?: EntitySchema[]): Promise<IDialect>;

package/dist/core/factory.js

@@ -0,0 +1,142 @@
+import { getDialectConfig, getSupportedDialects } from './config.js';
+import { getAllSchemas, registerSchemas } from './registry.js';
+/** Singleton dialect instance */
+let currentDialect = null;
+let currentConfig = null;
+/**
+ * Dynamically load a dialect adapter module.
+ * Only the selected dialect is loaded — no unused drivers in memory.
+ */
+async function loadDialectModule(dialect) {
+    switch (dialect) {
+        case 'mongodb': return import('../dialects/mongo.dialect.js');
+        case 'sqlite': return import('../dialects/sqlite.dialect.js');
+        case 'postgres': return import('../dialects/postgres.dialect.js');
+        case 'mysql': return import('../dialects/mysql.dialect.js');
+        case 'mariadb': return import('../dialects/mariadb.dialect.js');
+        case 'oracle': return import('../dialects/oracle.dialect.js');
+        case 'mssql': return import('../dialects/mssql.dialect.js');
+        case 'cockroachdb': return import('../dialects/cockroachdb.dialect.js');
+        case 'db2': return import('../dialects/db2.dialect.js');
+        case 'hana': return import('../dialects/hana.dialect.js');
+        case 'hsqldb': return import('../dialects/hsqldb.dialect.js');
+        case 'spanner': return import('../dialects/spanner.dialect.js');
+        case 'sybase': return import('../dialects/sybase.dialect.js');
+        default:
+            throw new Error(`No loader for dialect "${dialect}". Supported: ${getSupportedDialects().join(', ')}`);
+    }
+}
+/**
+ * Read the database configuration from environment variables.
+ *
+ * Required env vars:
+ *   DB_DIALECT  = mongodb | sqlite | postgres | mysql | mariadb | oracle | mssql | cockroachdb | db2 | hana | hsqldb | spanner | sybase
+ *   SGBD_URI    = connection string
+ *
+ * Throws if DB_DIALECT or SGBD_URI is missing.
+ */
+export function getConfigFromEnv() {
+    const dialect = process.env.DB_DIALECT;
+    const uri = process.env.SGBD_URI;
+    if (!dialect) {
+        throw new Error('DB_DIALECT is not defined in environment\n' +
+            `Supported: ${getSupportedDialects().join(', ')}`);
+    }
+    // Validate dialect name
+    getDialectConfig(dialect);
+    if (!uri) {
+        throw new Error(`SGBD_URI is not defined in environment\n` +
+            `DB_DIALECT=${dialect} requires a connection string in SGBD_URI`);
+    }
+    return {
+        dialect,
+        uri,
+        // Hibernate-inspired properties from env
+        showSql: process.env.DB_SHOW_SQL === 'true',
+        formatSql: process.env.DB_FORMAT_SQL === 'true',
+        schemaStrategy: process.env.DB_SCHEMA_STRATEGY || 'none',
+        poolSize: process.env.DB_POOL_SIZE ? Number(process.env.DB_POOL_SIZE) : undefined,
+        cacheEnabled: process.env.DB_CACHE_ENABLED === 'true',
+        cacheTtlSeconds: process.env.DB_CACHE_TTL ? Number(process.env.DB_CACHE_TTL) : undefined,
+        batchSize: process.env.DB_BATCH_SIZE ? Number(process.env.DB_BATCH_SIZE) : undefined,
+    };
+}
+/**
+ * Initialize and connect the dialect.
+ * Returns a singleton — subsequent calls return the same instance.
+ */
+export async function getDialect(config) {
+    if (currentDialect) {
+        return currentDialect;
+    }
+    const cfg = config || getConfigFromEnv();
+    const dialectCfg = getDialectConfig(cfg.dialect);
+    try {
+        const mod = await loadDialectModule(cfg.dialect);
+        currentDialect = mod.createDialect();
+        await currentDialect.connect(cfg);
+        currentConfig = cfg;
+        // Hibernate SessionFactory — register all entity models on first connection
+        await currentDialect.initSchema(getAllSchemas());
+        return currentDialect;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('Cannot find module') || message.includes('MODULE_NOT_FOUND')) {
+            throw new Error(`Dialect "${dialectCfg.label}" requires a driver. Install it:\n  ${dialectCfg.installHint}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Get the current dialect type without connecting.
+ */
+export function getCurrentDialectType() {
+    if (currentConfig)
+        return currentConfig.dialect;
+    return process.env.DB_DIALECT || 'mongodb';
+}
+/**
+ * Disconnect the current dialect and reset the singleton.
+ */
+export async function disconnectDialect() {
+    if (currentDialect) {
+        await currentDialect.disconnect();
+        currentDialect = null;
+        currentConfig = null;
+    }
+}
+/**
+ * Test the connection with a given config without changing the active dialect.
+ * Used by the setup wizard to validate before committing.
+ */
+export async function testConnection(config) {
+    try {
+        const mod = await loadDialectModule(config.dialect);
+        const dialect = mod.createDialect();
+        await dialect.connect(config);
+        const ok = await dialect.testConnection();
+        await dialect.disconnect();
+        return ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Simplified high-level API: connect to a database and optionally register schemas.
+ * Returns the connected dialect instance.
+ *
+ * Example:
+ *   const dialect = await createConnection({
+ *     dialect: 'sqlite',
+ *     uri: './my.db',
+ *     schemaStrategy: 'update',
+ *   }, [ContactSchema, OrderSchema]);
+ */
+export async function createConnection(config, schemas) {
+    if (schemas) {
+        registerSchemas(schemas);
+    }
+    return getDialect(config);
+}

package/dist/core/normalizer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalize a database document: _id → id, remove __v
+ * Works for any dialect output (MongoDB returns _id, SQL returns id)
+ */
+export declare function normalizeDoc<T = Record<string, unknown>>(doc: any): T;
+/**
+ * Normalize an array of documents
+ */
+export declare function normalizeDocs<T = Record<string, unknown>>(docs: any[]): T[];

package/dist/core/normalizer.js

@@ -0,0 +1,19 @@
+// Document normalizer — _id → id conversion
+// Author: Dr Hamid MADANI drmdh@msn.com
+/**
+ * Normalize a database document: _id → id, remove __v
+ * Works for any dialect output (MongoDB returns _id, SQL returns id)
+ */
+export function normalizeDoc(doc) {
+    if (!doc)
+        return doc;
+    const { _id, __v, ...rest } = doc;
+    const id = _id?.toString?.() ?? _id ?? rest.id;
+    return { id, ...rest };
+}
+/**
+ * Normalize an array of documents
+ */
+export function normalizeDocs(docs) {
+    return docs.map(d => normalizeDoc(d));
+}

package/dist/core/registry.d.ts

@@ -0,0 +1,43 @@
+import type { EntitySchema } from './types.js';
+/**
+ * Register a single entity schema into the registry.
+ * Equivalent to Hibernate's @Entity annotation scanning.
+ */
+export declare function registerSchema(schema: EntitySchema): void;
+/**
+ * Register multiple entity schemas at once (batch registration).
+ */
+export declare function registerSchemas(schemas: EntitySchema[]): void;
+/**
+ * Get an entity schema by entity name (e.g. 'Client', 'Ticket')
+ * Throws if the entity is not registered.
+ */
+export declare function getSchema(entityName: string): EntitySchema;
+/**
+ * Get an entity schema by collection/table name (e.g. 'clients', 'tickets')
+ */
+export declare function getSchemaByCollection(collection: string): EntitySchema | undefined;
+/**
+ * Get all registered entity schemas
+ */
+export declare function getAllSchemas(): EntitySchema[];
+/**
+ * Get all entity names
+ */
+export declare function getEntityNames(): string[];
+/**
+ * Check if an entity is registered
+ */
+export declare function hasSchema(entityName: string): boolean;
+/**
+ * Validate all schemas: check that relation targets exist in the registry.
+ * Call this at application startup to catch configuration errors early.
+ */
+export declare function validateSchemas(): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Clear all registered schemas (useful for testing)
+ */
+export declare function clearRegistry(): void;

package/dist/core/registry.js

@@ -0,0 +1,78 @@
+/** Map of entity name -> EntitySchema */
+const registry = new Map();
+/** Map of collection name -> EntitySchema */
+const collectionMap = new Map();
+/**
+ * Register a single entity schema into the registry.
+ * Equivalent to Hibernate's @Entity annotation scanning.
+ */
+export function registerSchema(schema) {
+    registry.set(schema.name, schema);
+    collectionMap.set(schema.collection, schema);
+}
+/**
+ * Register multiple entity schemas at once (batch registration).
+ */
+export function registerSchemas(schemas) {
+    for (const schema of schemas) {
+        registerSchema(schema);
+    }
+}
+/**
+ * Get an entity schema by entity name (e.g. 'Client', 'Ticket')
+ * Throws if the entity is not registered.
+ */
+export function getSchema(entityName) {
+    const schema = registry.get(entityName);
+    if (!schema) {
+        throw new Error(`Entity "${entityName}" is not registered. ` +
+            `Available entities: ${Array.from(registry.keys()).join(', ')}`);
+    }
+    return schema;
+}
+/**
+ * Get an entity schema by collection/table name (e.g. 'clients', 'tickets')
+ */
+export function getSchemaByCollection(collection) {
+    return collectionMap.get(collection);
+}
+/**
+ * Get all registered entity schemas
+ */
+export function getAllSchemas() {
+    return Array.from(registry.values());
+}
+/**
+ * Get all entity names
+ */
+export function getEntityNames() {
+    return Array.from(registry.keys());
+}
+/**
+ * Check if an entity is registered
+ */
+export function hasSchema(entityName) {
+    return registry.has(entityName);
+}
+/**
+ * Validate all schemas: check that relation targets exist in the registry.
+ * Call this at application startup to catch configuration errors early.
+ */
+export function validateSchemas() {
+    const errors = [];
+    for (const schema of registry.values()) {
+        for (const [field, relation] of Object.entries(schema.relations)) {
+            if (!registry.has(relation.target)) {
+                errors.push(`${schema.name}.${field} references unknown entity "${relation.target}"`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Clear all registered schemas (useful for testing)
+ */
+export function clearRegistry() {
+    registry.clear();
+    collectionMap.clear();
+}