@tylix/orm 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,30 @@
+# @tylix/orm
+
+A lightweight ORM for Tylix applications with adapters for SQLite,
+PostgreSQL, MySQL, and MongoDB.
+
+## What's included
+
+- **Adapters** — `DatabaseAdapter` (base interface), `SqliteAdapter`,
+  `PostgresAdapter`, `MysqlAdapter`, `MongoAdapter`, selected at
+  runtime via `AdapterFactory`
+- **Model** — `Model` base class, backed by `ConnectionManager`
+- **Query** — `QueryBuilder` and `buildSelectSql` for building queries
+  independent of the underlying adapter
+
+## Usage
+
+```js
+import { Model, QueryBuilder } from '@tylix/orm'
+
+class Invoice extends Model {
+  static table = 'invoices'
+}
+```
+
+Ships with a `d.ts` declaration file. Pairs with the model/migration
+templates in `@tylix/generator`.
+
+## License
+
+MIT

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@tylix/orm",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "scripts": {
     "test": "node --test src/**/*.test.js"
   },

package/src/adapters/AdapterFactory.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseAdapter } from './DatabaseAdapter.js';
+
+export interface DatabaseConfig {
+    driver: 'sqlite' | 'postgres' | 'mysql' | 'mongodb';
+    [key: string]: unknown;
+}
+
+export declare function createAdapter(databaseConfig: DatabaseConfig): DatabaseAdapter;

package/src/adapters/AdapterFactory.js

@@ -1,24 +1,24 @@
-import { SqliteAdapter } from "./SqliteAdapter.js";
-import { PostgresAdapter } from "./PostgresAdapter.js";
-import { MysqlAdapter } from "./MysqlAdapter.js";
-import { MongoAdapter } from "./MongoAdapter.js";
+import { SqliteAdapter } from './SqliteAdapter.js'
+import { PostgresAdapter } from './PostgresAdapter.js'
+import { MysqlAdapter } from './MysqlAdapter.js'
+import { MongoAdapter } from './MongoAdapter.js'
 
 const ADAPTERS = {
   sqlite: SqliteAdapter,
   postgres: PostgresAdapter,
   mysql: MysqlAdapter,
   mongodb: MongoAdapter,
-};
+}
 
 export function createAdapter(databaseConfig) {
-  const { driver, ...options } = databaseConfig;
+  const { driver, ...options } = databaseConfig
 
-  const AdapterClass = ADAPTERS[driver];
+  const AdapterClass = ADAPTERS[driver]
   if (!AdapterClass) {
     throw new Error(
-      `Unknown database driver "${driver}". Available drivers: ${Object.keys(ADAPTERS).join(", ")}`
-    );
+      `Unknown database driver "${driver}". Available drivers: ${Object.keys(ADAPTERS).join(', ')}`,
+    )
   }
 
-  return new AdapterClass(options);
+  return new AdapterClass(options)
 }

package/src/adapters/DatabaseAdapter.d.ts

@@ -0,0 +1,18 @@
+import type { QueryDescriptor } from '../query/types.js';
+
+export interface RunResult {
+    lastInsertRowid: number;
+}
+
+export declare class DatabaseAdapter {
+    connect(): Promise<this>;
+    close(): Promise<void>;
+    run(sql: string, params?: unknown[]): Promise<RunResult>;
+    get(sql: string, params?: unknown[]): Promise<Record<string, unknown> | null>;
+    all(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    columnType(logicalType: string): string | null;
+    count(table: string): Promise<number>;
+    paginate(table: string, limit: number, offset: number): Promise<Record<string, unknown>[]>;
+    listTables(): Promise<string[]>;
+    query(table: string, descriptor?: QueryDescriptor): Promise<Record<string, unknown>[]>;
+}

package/src/adapters/MongoAdapter.d.ts

@@ -0,0 +1,23 @@
+import { DatabaseAdapter } from './DatabaseAdapter.js';
+
+export interface MongoAdapterOptions {
+    url?: string;
+    database?: string;
+}
+
+export type ParsedMongoQuery =
+    | { type: 'createTable'; table: string }
+    | { type: 'dropTable'; table: string }
+    | { type: 'alterAddColumn'; table: string; column: string }
+    | { type: 'alterDropColumn'; table: string; column: string }
+    | { type: 'findOne'; table: string; field: string }
+    | { type: 'findAll'; table: string }
+    | { type: 'insert'; table: string; columns: string[] }
+    | { type: 'update'; table: string; columns: string[]; whereField: string }
+    | { type: 'delete'; table: string; field: string };
+
+export declare function parseQuery(sql: string): ParsedMongoQuery;
+
+export declare class MongoAdapter extends DatabaseAdapter {
+    constructor(options?: MongoAdapterOptions);
+}

package/src/adapters/MongoAdapter.js

@@ -85,6 +85,10 @@ export class MongoAdapter extends DatabaseAdapter {
     }
   }
 
+  quoteIdentifier(name) {
+    return name
+  }
+
   ensureConnected() {
     if (!this.db) {
       throw new Error('MongoAdapter is not connected. Call connect() first.')

package/src/adapters/MysqlAdapter.d.ts

@@ -0,0 +1,15 @@
+import { DatabaseAdapter } from './DatabaseAdapter.js';
+
+export interface MysqlAdapterOptions {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+}
+
+export declare class MysqlAdapter extends DatabaseAdapter {
+    constructor(options?: MysqlAdapterOptions);
+}
+
+export declare function toMysqlDateTime(value: unknown): unknown;

package/src/adapters/MysqlAdapter.js

@@ -41,6 +41,10 @@ export class MysqlAdapter extends DatabaseAdapter {
     }
   }
 
+  quoteIdentifier(name) {
+    return `\`${name.replace(/`/g, '``')}\``
+  }
+
   ensureConnected() {
     if (!this.connection) {
       throw new Error('MysqlAdapter is not connected. Call connect() first.')

package/src/adapters/PostgresAdapter.d.ts

@@ -0,0 +1,17 @@
+import { DatabaseAdapter } from './DatabaseAdapter.js';
+
+export interface PostgresAdapterOptions {
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+}
+
+export declare class PostgresAdapter extends DatabaseAdapter {
+    constructor(options?: PostgresAdapterOptions);
+}
+
+export declare function toPositionalPlaceholders(sql: string): string;
+export declare function ensureReturningId(sql: string): string;

package/src/adapters/PostgresAdapter.js

@@ -40,7 +40,6 @@ export class PostgresAdapter extends DatabaseAdapter {
     this.pool = new pg.Pool(this.config)
     return this
   }
-
   async close() {
     if (this.pool) {
       await this.pool.end()
@@ -48,6 +47,10 @@ export class PostgresAdapter extends DatabaseAdapter {
     }
   }
 
+  quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`
+  }
+
   ensureConnected() {
     if (!this.pool) {
       throw new Error('PostgresAdapter is not connected. Call connect() first.')

package/src/adapters/SqliteAdapter.d.ts

@@ -0,0 +1,9 @@
+import { DatabaseAdapter } from './DatabaseAdapter.js';
+
+export interface SqliteAdapterOptions {
+    filename?: string;
+}
+
+export declare class SqliteAdapter extends DatabaseAdapter {
+    constructor(options?: SqliteAdapterOptions);
+}

package/src/adapters/SqliteAdapter.js

@@ -32,6 +32,10 @@ export class SqliteAdapter extends DatabaseAdapter {
     }
   }
 
+  quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`
+  }
+
   ensureConnected() {
     if (!this.db) {
       throw new Error('SqliteAdapter is not connected. Call connect() first.')

package/src/ensureDatabaseExists.js

@@ -0,0 +1,64 @@
+import pg from 'pg'
+import mysql from 'mysql2/promise'
+
+export async function ensureDatabaseExists(databaseConfig) {
+  const { driver } = databaseConfig
+  if (driver === 'postgres') {
+    await ensurePostgresDatabase(databaseConfig)
+  } else if (driver === 'mysql') {
+    await ensureMysqlDatabase(databaseConfig)
+  }
+  // sqlite: the file is created automatically on connect, nothing to do here.
+  // mongodb: databases/collections are created lazily on first write, nothing to do here.
+}
+
+async function ensurePostgresDatabase({
+  connectionString,
+  host,
+  port,
+  user,
+  password,
+  database,
+}) {
+  // A connection string can already point at a specific target db and
+  // may not even include a "postgres" admin database to fall back to --
+  // safest to skip auto-create rather than guess at rewriting it.
+  if (connectionString) return
+
+  const adminPool = new pg.Pool({
+    host,
+    port,
+    user,
+    password,
+    database: 'postgres',
+  })
+  try {
+    const { rows } = await adminPool.query(
+      'SELECT 1 FROM pg_database WHERE datname = $1',
+      [database],
+    )
+    if (rows.length === 0) {
+      // Postgres doesn't support "CREATE DATABASE IF NOT EXISTS", and
+      // database names can't be parameterized -- quote defensively.
+      await adminPool.query(`CREATE DATABASE "${database.replace(/"/g, '""')}"`)
+    }
+  } finally {
+    await adminPool.end()
+  }
+}
+
+async function ensureMysqlDatabase({ host, port, user, password, database }) {
+  const connection = await mysql.createConnection({
+    host,
+    port,
+    user,
+    password,
+  })
+  try {
+    await connection.query(
+      `CREATE DATABASE IF NOT EXISTS \`${database.replace(/`/g, '``')}\``,
+    )
+  } finally {
+    await connection.end()
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./adapters/DatabaseAdapter.js";
+export * from "./adapters/SqliteAdapter.js";
+export * from "./adapters/PostgresAdapter.js";
+export * from "./model/ConnectionManager.js";
+export * from "./model/Model.js";
+export * from "./adapters/AdapterFactory.js";
+export * from "./adapters/MysqlAdapter.js";
+export * from "./adapters/MongoAdapter.js";
+export * from "./query/QueryBuilder.js";
+export * from "./query/buildSelectSql.js";
+export * from "./query/types.js";

package/src/index.js

@@ -1,9 +1,11 @@
-export * from "./adapters/DatabaseAdapter.js";
-export * from "./adapters/SqliteAdapter.js";
-export * from "./model/ConnectionManager.js";
-export * from "./model/Model.js";
-export * from "./adapters/AdapterFactory.js";
-export * from "./adapters/MysqlAdapter.js";
-export * from "./adapters/MongoAdapter.js";
-export * from "./query/QueryBuilder.js";
-export * from "./query/buildSelectSql.js";
+export * from './adapters/DatabaseAdapter.js'
+export * from './adapters/SqliteAdapter.js'
+export * from './adapters/PostgresAdapter.js'
+export * from './model/ConnectionManager.js'
+export * from './model/Model.js'
+export * from './adapters/AdapterFactory.js'
+export * from './adapters/MysqlAdapter.js'
+export * from './adapters/MongoAdapter.js'
+export * from './query/QueryBuilder.js'
+export * from './query/buildSelectSql.js'
+export * from './ensureDatabaseExists.js'

package/src/model/ConnectionManager.d.ts

@@ -0,0 +1,7 @@
+import type { DatabaseAdapter } from '../adapters/DatabaseAdapter.js';
+
+export declare const ConnectionManager: {
+    setAdapter(adapter: DatabaseAdapter): void;
+    getAdapter(): DatabaseAdapter;
+    reset(): void;
+};

package/src/model/Model.d.ts

@@ -0,0 +1,49 @@
+// orm/src/model/Model.d.ts
+import { QueryBuilder } from '../query/QueryBuilder.js';
+
+interface PaginateOptions {
+    page?: number;
+    limit?: number;
+    where?: Record<string, unknown>;
+}
+
+interface PaginateResult<T> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+
+export declare class Model {
+    static table: string | null;
+    static fillable: string[];
+    static timestamps: boolean;
+
+    static getTable(): string;
+    static getAdapter(): unknown;
+
+    static all(): Promise<Record<string, unknown>[]>;
+    static query(): QueryBuilder<Record<string, unknown>>;
+    static paginate(options?: PaginateOptions): Promise<PaginateResult<Record<string, unknown>>>;
+    static find(id: number | string): Promise<Record<string, unknown> | null>;
+    static create(data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    static update(id: number | string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    static delete(id: number | string): Promise<boolean>;
+
+    static belongsTo(
+        row: Record<string, unknown> | null,
+        foreignKey: string,
+        RelatedModel: typeof Model,
+    ): Promise<Record<string, unknown> | null>;
+    static hasMany(
+        row: { id: number },
+        RelatedModel: typeof Model,
+        foreignKey: string,
+    ): Promise<Record<string, unknown>[]>;
+
+    static first(): Promise<Record<string, unknown> | null>;
+    static count(): Promise<number>;
+}

package/src/model/Model.js

@@ -30,14 +30,18 @@ export class Model {
     return new QueryBuilder(this)
   }
 
-  static async paginate({ page = 1, limit = 20 } = {}) {
-    const adapter = ConnectionManager.getAdapter()
+  static async paginate({ page = 1, limit = 20, where = {} } = {}) {
     const safePage = Math.max(1, Math.floor(page))
     const safeLimit = Math.max(1, Math.min(100, Math.floor(limit)))
     const offset = (safePage - 1) * safeLimit
 
-    const total = await adapter.count(this.getTable())
-    const data = await adapter.paginate(this.getTable(), safeLimit, offset)
+    let query = this.query()
+    for (const [field, value] of Object.entries(where)) {
+      query = query.where(field, value)
+    }
+
+    const total = await query.count()
+    const data = await query.limit(safeLimit).offset(offset).get()
 
     return {
       data,
@@ -49,7 +53,6 @@ export class Model {
       },
     }
   }
-
   static async find(id) {
     const adapter = ConnectionManager.getAdapter()
     return adapter.get(`SELECT * FROM ${this.getTable()} WHERE id = ?`, [id])

package/src/query/QueryBuilder.d.ts

@@ -0,0 +1,16 @@
+import type { WhereClause, QueryDescriptor } from './types.js';
+
+export declare class QueryBuilder<TRow> {
+    constructor(ModelClass: { getAdapter(): unknown; getTable(): string });
+
+    where(field: string, value: unknown): this;
+    where(field: string, operator: WhereClause['operator'], value: unknown): this;
+    orderBy(field: string, direction?: 'ASC' | 'DESC'): this;
+    limit(value: number): this;
+    offset(value: number): this;
+    toDescriptor(): QueryDescriptor;
+
+    get(): Promise<TRow[]>;
+    first(): Promise<TRow | null>;
+    count(): Promise<number>;
+}

package/src/query/buildSelectSql.d.ts

@@ -0,0 +1,11 @@
+import type { QueryDescriptor } from './types.js';
+
+export interface BuiltSelect {
+    sql: string;
+    params: unknown[];
+}
+
+export declare function buildSelectSql(
+    table: string,
+    descriptor?: QueryDescriptor
+): BuiltSelect;

package/src/query/types.d.ts

@@ -0,0 +1,18 @@
+// src/query/types.d.ts
+export interface WhereClause {
+  field: string
+  operator: '=' | '!=' | '>' | '<' | '>=' | '<='
+  value: unknown
+}
+
+export interface OrderClause {
+  field: string
+  direction: 'ASC' | 'DESC'
+}
+
+export interface QueryDescriptor {
+  wheres: WhereClause[]
+  orders: OrderClause[]
+  limitValue?: number
+  offsetValue?: number
+}

package/src/query/types.js

@@ -0,0 +1,4 @@
+// No runtime values — this module exists purely so its .d.ts sibling
+// can export shared query-shape types (WhereClause, QueryDescriptor)
+// referenced by QueryBuilder and DatabaseAdapter.
+export {}

package/src/types.ts

@@ -0,0 +1,25 @@
+
+
+export interface ColumnBuilder {
+  unique(): void;
+}
+
+export interface TableBuilder {
+  increments(name: string): ColumnBuilder;
+  string(name: string): ColumnBuilder;
+  text(name: string): ColumnBuilder;
+  boolean(name: string): ColumnBuilder;
+  integer(name: string): ColumnBuilder;
+  date(name: string): ColumnBuilder;
+  datetime(name: string): ColumnBuilder;
+  json(name: string): ColumnBuilder;
+  timestamps(): void;
+  // present only in alterTable's callback, absent from createTable's
+  dropColumn?(name: string): void;
+}
+
+export interface Schema {
+  createTable(tableName: string, callback: (table: TableBuilder) => void | Promise<void>): Promise<void>;
+  dropTable(tableName: string): Promise<void>;
+  alterTable(tableName: string, callback: (table: TableBuilder) => void | Promise<void>): Promise<void>;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": false,
+    "noEmit": true,
+    "strict": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}