@tylix/orm 0.5.0 → 0.6.0

package/src/model/Model.d.ts

@@ -1,5 +1,6 @@
 // orm/src/model/Model.d.ts
 import { QueryBuilder } from '../query/QueryBuilder.js';
+import type { WhereClause } from '../query/types.js';
 
 interface PaginateOptions {
     page?: number;
@@ -17,6 +18,8 @@ interface PaginateResult<T> {
     };
 }
 
+type Row = Record<string, unknown>;
+
 export declare class Model {
     static table: string | null;
     static fillable: string[];
@@ -25,25 +28,42 @@ export declare class Model {
     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 all(): Promise<Row[]>;
+    static query(): QueryBuilder<Row>;
+    static where(field: string, value: unknown): QueryBuilder<Row>;
+    static where(field: string, operator: WhereClause['operator'], value: unknown): QueryBuilder<Row>;
+    static whereNull(field: string): QueryBuilder<Row>;
+    static whereNotNull(field: string): QueryBuilder<Row>;
+    static whereIn(field: string, values: readonly unknown[]): QueryBuilder<Row>;
+    static whereNotIn(field: string, values: readonly unknown[]): QueryBuilder<Row>;
+    static latest(column?: string): QueryBuilder<Row>;
+    static oldest(column?: string): QueryBuilder<Row>;
+    static paginate(options?: PaginateOptions): Promise<PaginateResult<Row>>;
+    static find(id: number | string): Promise<Row | null>;
+    static findOrFail(id: number | string): Promise<Row>;
+    static create(data: Row): Promise<Row | null>;
+    static update(id: number | string, data: Row): Promise<Row | null>;
     static delete(id: number | string): Promise<boolean>;
+    static destroy(...ids: Array<number | string | Array<number | string>>): Promise<number>;
+
+    static firstOrCreate(attributes: Row, values?: Row): Promise<Row | null>;
+    static updateOrCreate(attributes: Row, values?: Row): Promise<Row | null>;
+
+    static pluck(column: string): Promise<unknown[]>;
+    static pluck(column: string, keyColumn: string): Promise<Record<string, unknown>>;
+    static exists(): Promise<boolean>;
 
     static belongsTo(
-        row: Record<string, unknown> | null,
+        row: Row | null,
         foreignKey: string,
         RelatedModel: typeof Model,
-    ): Promise<Record<string, unknown> | null>;
+    ): Promise<Row | null>;
     static hasMany(
         row: { id: number },
         RelatedModel: typeof Model,
         foreignKey: string,
-    ): Promise<Record<string, unknown>[]>;
+    ): Promise<Row[]>;
 
-    static first(): Promise<Record<string, unknown> | null>;
+    static first(): Promise<Row | null>;
     static count(): Promise<number>;
 }

package/src/model/Model.js

@@ -30,6 +30,46 @@ export class Model {
     return new QueryBuilder(this)
   }
 
+  /**
+   * Shortcut for query().where(...):
+   *   await Post.where("status", "published").get()
+   *   await Post.where("views", ">", 100).first()
+   *   await Post.where("deleted_at", null).get()      // IS NULL
+   */
+  static where(...args) {
+    return this.query().where(...args)
+  }
+
+  /** deleted_at IS NULL. Returns a QueryBuilder: await Post.whereNull("deleted_at").get() */
+  static whereNull(field) {
+    return this.query().whereNull(field)
+  }
+
+  /** verified_at IS NOT NULL. Returns a QueryBuilder. */
+  static whereNotNull(field) {
+    return this.query().whereNotNull(field)
+  }
+
+  /** id IN (1, 2, 3). Returns a QueryBuilder: await Post.whereIn("id", [1, 2]).get() */
+  static whereIn(field, values) {
+    return this.query().whereIn(field, values)
+  }
+
+  /** status NOT IN ("banned", "spam"). Returns a QueryBuilder. */
+  static whereNotIn(field, values) {
+    return this.query().whereNotIn(field, values)
+  }
+
+  /** Newest first. Returns a QueryBuilder: await Post.latest().get() */
+  static latest(column = 'created_at') {
+    return this.query().latest(column)
+  }
+
+  /** Oldest first. Returns a QueryBuilder: await Post.oldest().first() */
+  static oldest(column = 'created_at') {
+    return this.query().oldest(column)
+  }
+
   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)))
@@ -53,11 +93,23 @@ export class Model {
       },
     }
   }
+
   static async find(id) {
     const adapter = ConnectionManager.getAdapter()
     return adapter.get(`SELECT * FROM ${this.getTable()} WHERE id = ?`, [id])
   }
 
+  /** Like find(), but throws (with err.status = 404) when the row is missing. */
+  static async findOrFail(id) {
+    const row = await this.find(id)
+    if (!row) {
+      const error = new Error(`${this.name} with id ${id} not found.`)
+      error.status = 404
+      throw error
+    }
+    return row
+  }
+
   static async create(data) {
     const adapter = ConnectionManager.getAdapter()
     const fields = this.fillable.filter((f) => f in data)
@@ -119,6 +171,95 @@ export class Model {
     return true
   }
 
+  /**
+   * Delete one or more rows by id and return how many actually existed:
+   *   await Post.destroy(1)
+   *   await Post.destroy(1, 2, 3)
+   *   await Post.destroy([1, 2, 3])
+   */
+  static async destroy(...ids) {
+    const flat = ids.flat().filter((id) => id !== undefined && id !== null)
+    if (flat.length === 0) {
+      throw new Error(`${this.name}.destroy() needs at least one id.`)
+    }
+
+    let deleted = 0
+    for (const id of flat) {
+      if (await this.find(id)) {
+        await this.delete(id)
+        deleted++
+      }
+    }
+    return deleted
+  }
+
+  /**
+   * Find the first row matching `attributes`, or create it with
+   * `attributes` + `values`:
+   *   await User.firstOrCreate({ email: "a@b.com" }, { name: "Ann" })
+   */
+  static async firstOrCreate(attributes, values = {}) {
+    const keys = Object.keys(attributes ?? {})
+    if (keys.length === 0) {
+      throw new Error(
+        `${this.name}.firstOrCreate() needs at least one attribute to match on.`,
+      )
+    }
+
+    let query = this.query()
+    for (const key of keys) {
+      query = query.where(key, attributes[key])
+    }
+
+    const existing = await query.first()
+    if (existing) return existing
+
+    return this.create({ ...attributes, ...values })
+  }
+
+  /**
+   * Find the first row matching `attributes` and update it with `values`,
+   * or create it with `attributes` + `values`:
+   *   await Setting.updateOrCreate({ key: "theme" }, { value: "dark" })
+   */
+  static async updateOrCreate(attributes, values = {}) {
+    const keys = Object.keys(attributes ?? {})
+    if (keys.length === 0) {
+      throw new Error(
+        `${this.name}.updateOrCreate() needs at least one attribute to match on.`,
+      )
+    }
+
+    let query = this.query()
+    for (const key of keys) {
+      query = query.where(key, attributes[key])
+    }
+
+    const existing = await query.first()
+    if (!existing) {
+      return this.create({ ...attributes, ...values })
+    }
+
+    const hasFillableChange = this.fillable.some((f) => f in values)
+    if (!hasFillableChange) return existing
+
+    return this.update(existing.id, values)
+  }
+
+  /**
+   * One column as a plain array (or an object when a key column is given):
+   *   await User.pluck("email")           -> ["a@b.com", "c@d.com"]
+   *   await User.pluck("email", "id")     -> { 1: "a@b.com", 2: "c@d.com" }
+   */
+  static async pluck(column, keyColumn) {
+    return this.query().pluck(column, keyColumn)
+  }
+
+  /** True when the table has at least one row. */
+  static async exists() {
+    return this.query().exists()
+  }
+
   static async belongsTo(row, foreignKey, RelatedModel) {
     if (!row || row[foreignKey] === undefined || row[foreignKey] === null) {
       return null
@@ -141,4 +282,4 @@ export class Model {
   static async count() {
     return this.query().count()
   }
-}
+}

package/src/query/QueryBuilder.d.ts

@@ -5,7 +5,13 @@ export declare class QueryBuilder<TRow> {
 
     where(field: string, value: unknown): this;
     where(field: string, operator: WhereClause['operator'], value: unknown): this;
+    whereNull(field: string): this;
+    whereNotNull(field: string): this;
+    whereIn(field: string, values: readonly unknown[]): this;
+    whereNotIn(field: string, values: readonly unknown[]): this;
     orderBy(field: string, direction?: 'ASC' | 'DESC'): this;
+    latest(column?: string): this;
+    oldest(column?: string): this;
     limit(value: number): this;
     offset(value: number): this;
     toDescriptor(): QueryDescriptor;
@@ -13,4 +19,7 @@ export declare class QueryBuilder<TRow> {
     get(): Promise<TRow[]>;
     first(): Promise<TRow | null>;
     count(): Promise<number>;
+    pluck(column: string): Promise<unknown[]>;
+    pluck(column: string, keyColumn: string): Promise<Record<string, unknown>>;
+    exists(): Promise<boolean>;
 }

package/src/query/QueryBuilder.js

@@ -1,7 +1,7 @@
 /**
  * Fluent query builder returned by Model.query(). Accumulates a
  * structured descriptor and only hits the database when a terminal
- * method (get/first/count) is called.
+ * method (get/first/count/pluck/exists) is called.
  */
 export class QueryBuilder {
   constructor(ModelClass) {
@@ -12,6 +12,10 @@ export class QueryBuilder {
     this.offsetValue = undefined;
   }
 
+  // where("status", "active")        status = 'active'
+  // where("age", ">", 18)            age > 18
+  // where("deleted_at", null)        deleted_at IS NULL
+  // where("id", "IN", [1, 2, 3])     same as whereIn("id", [1, 2, 3])
   where(field, operatorOrValue, maybeValue) {
     const hasExplicitOperator = maybeValue !== undefined;
     const operator = hasExplicitOperator ? operatorOrValue : "=";
@@ -21,6 +25,36 @@ export class QueryBuilder {
     return this;
   }
 
+  // deleted_at IS NULL
+  whereNull(field) {
+    this.wheres.push({ field, operator: "IS NULL", value: null });
+    return this;
+  }
+
+  // deleted_at IS NOT NULL
+  whereNotNull(field) {
+    this.wheres.push({ field, operator: "IS NOT NULL", value: null });
+    return this;
+  }
+
+  // id IN (1, 2, 3). An empty array matches nothing.
+  whereIn(field, values) {
+    if (!Array.isArray(values)) {
+      throw new Error("whereIn() needs an array of values.");
+    }
+    this.wheres.push({ field, operator: "IN", value: [...values] });
+    return this;
+  }
+
+  // id NOT IN (1, 2, 3). An empty array excludes nothing.
+  whereNotIn(field, values) {
+    if (!Array.isArray(values)) {
+      throw new Error("whereNotIn() needs an array of values.");
+    }
+    this.wheres.push({ field, operator: "NOT IN", value: [...values] });
+    return this;
+  }
+
   orderBy(field, direction = "ASC") {
     const normalized = direction.toUpperCase();
     if (normalized !== "ASC" && normalized !== "DESC") {
@@ -30,6 +64,16 @@ export class QueryBuilder {
     return this;
   }
 
+  // Newest first (by created_at unless another column is given).
+  latest(column = "created_at") {
+    return this.orderBy(column, "DESC");
+  }
+
+  // Oldest first (by created_at unless another column is given).
+  oldest(column = "created_at") {
+    return this.orderBy(column, "ASC");
+  }
+
   limit(value) {
     this.limitValue = value;
     return this;
@@ -63,4 +107,19 @@ export class QueryBuilder {
     const rows = await this.get();
     return rows.length;
   }
-}
+
+  // pluck("email")        -> ["a@b.com", ...]
+  // pluck("email", "id")  -> { 1: "a@b.com", ... }
+  async pluck(column, keyColumn) {
+    const rows = await this.get();
+    if (keyColumn === undefined) {
+      return rows.map((row) => row[column]);
+    }
+    return Object.fromEntries(rows.map((row) => [row[keyColumn], row[column]]));
+  }
+
+  async exists() {
+    const row = await this.first();
+    return row !== null;
+  }
+}

package/src/query/buildSelectSql.js

@@ -1,4 +1,91 @@
-const SUPPORTED_OPERATORS = ["=", "!=", ">", "<", ">=", "<="];
+const COMPARISON_OPERATORS = ["=", "!=", "<>", ">", "<", ">=", "<="];
+const NULL_OPERATORS = ["IS NULL", "IS NOT NULL"];
+const LIST_OPERATORS = ["IN", "NOT IN"];
+
+// "like" and other lowercase spellings are accepted and normalized first.
+const SUPPORTED_OPERATORS = [
+  ...COMPARISON_OPERATORS,
+  "LIKE",
+  ...NULL_OPERATORS,
+  ...LIST_OPERATORS,
+];
+
+// What a LIKE condition is written as in SQL. MySQL and SQLite are already
+// case-insensitive for LIKE, so they keep "LIKE"; PostgreSQL is
+// case-sensitive, so its adapter asks for "ILIKE" to behave the same way.
+const LIKE_OPERATORS = ["LIKE", "ILIKE"];
+
+// Each value in an IN list is its own "?" placeholder, and every driver caps
+// the number of placeholders per statement.
+const MAX_LIST_VALUES = 1000;
+
+// Letters, digits and underscores only, with an optional "table.column" form.
+// Rejects spaces, quotes, semicolons, comments and anything else that could
+// change the shape of the query.
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+
+function assertIdentifier(name, kind) {
+  if (typeof name !== "string" || !IDENTIFIER.test(name)) {
+    throw new Error(`Invalid ${kind} name "${String(name)}".`);
+  }
+  return name;
+}
+
+function normalizeOperator(operator) {
+  return String(operator).trim().replace(/\s+/g, " ").toUpperCase();
+}
+
+// Builds one WHERE condition and pushes its values onto `params`.
+function buildCondition(w, likeOperator, params) {
+  const operator = normalizeOperator(w.operator);
+  if (!SUPPORTED_OPERATORS.includes(operator)) {
+    throw new Error(
+      `Unsupported where operator "${w.operator}". Supported: ${SUPPORTED_OPERATORS.join(", ")}`
+    );
+  }
+
+  const column = assertIdentifier(w.field, "column");
+
+  if (NULL_OPERATORS.includes(operator)) {
+    return `${column} ${operator}`;
+  }
+
+  if (LIST_OPERATORS.includes(operator)) {
+    const values = w.value;
+    if (!Array.isArray(values)) {
+      throw new Error(`Operator "${operator}" needs an array of values.`);
+    }
+    if (values.length > MAX_LIST_VALUES) {
+      throw new Error(
+        `Operator "${operator}" accepts at most ${MAX_LIST_VALUES} values, got ${values.length}.`
+      );
+    }
+    // NULL never matches inside IN, and a single NULL makes NOT IN match
+    // nothing at all, so reject it instead of returning surprising rows.
+    if (values.some((v) => v === null || v === undefined)) {
+      throw new Error(
+        `"${operator}" lists cannot contain null or undefined. Use whereNull() / whereNotNull() for null checks.`
+      );
+    }
+    // "IN ()" is invalid SQL. An empty IN matches nothing; an empty NOT IN
+    // excludes nothing.
+    if (values.length === 0) {
+      return operator === "IN" ? "1 = 0" : "1 = 1";
+    }
+    params.push(...values);
+    return `${column} ${operator} (${values.map(() => "?").join(", ")})`;
+  }
+
+  // "= NULL" and "!= NULL" are never true in SQL, so translate them.
+  if (w.value === null) {
+    if (operator === "=") return `${column} IS NULL`;
+    if (operator === "!=" || operator === "<>") return `${column} IS NOT NULL`;
+    throw new Error(`Operator "${operator}" cannot be used with null.`);
+  }
+
+  params.push(w.value);
+  return `${column} ${operator === "LIKE" ? likeOperator : operator} ?`;
+}
 
 /**
  * Translates a structured query descriptor into a "?"-placeholder SQL
@@ -8,29 +95,38 @@ const SUPPORTED_OPERATORS = ["=", "!=", ">", "<", ">=", "<="];
  * translation and datetime conversion correctly per driver, so this
  * only needs to speak the common "?" dialect.
  *
+ * Values are always passed as parameters. Table and column names cannot be
+ * parameters, so they are validated as plain identifiers instead.
+ *
  * limit/offset are inlined as validated integers rather than passed as
  * placeholders, since mysql2 does not reliably support placeholders in
  * LIMIT/OFFSET position (same reasoning as Model.paginate()).
+ *
+ * options.likeOperator: "LIKE" (default) or "ILIKE", used for LIKE conditions.
  */
-export function buildSelectSql(table, { wheres = [], orders = [], limitValue, offsetValue } = {}) {
+export function buildSelectSql(
+  table,
+  { wheres = [], orders = [], limitValue, offsetValue } = {},
+  { likeOperator = "LIKE" } = {}
+) {
+  if (!LIKE_OPERATORS.includes(likeOperator)) {
+    throw new Error(
+      `Unsupported likeOperator "${likeOperator}". Use: ${LIKE_OPERATORS.join(", ")}`
+    );
+  }
+
   const params = [];
-  let sql = `SELECT * FROM ${table}`;
+  let sql = `SELECT * FROM ${assertIdentifier(table, "table")}`;
 
   if (wheres.length > 0) {
-    const clauses = wheres.map((w) => {
-      if (!SUPPORTED_OPERATORS.includes(w.operator)) {
-        throw new Error(
-          `Unsupported where operator "${w.operator}". Supported: ${SUPPORTED_OPERATORS.join(", ")}`
-        );
-      }
-      params.push(w.value);
-      return `${w.field} ${w.operator} ?`;
-    });
+    const clauses = wheres.map((w) => buildCondition(w, likeOperator, params));
     sql += ` WHERE ${clauses.join(" AND ")}`;
   }
 
   if (orders.length > 0) {
-    const clauses = orders.map((o) => `${o.field} ${o.direction}`);
+    const clauses = orders.map(
+      (o) => `${assertIdentifier(o.field, "column")} ${o.direction}`
+    );
     sql += ` ORDER BY ${clauses.join(", ")}`;
   }
 
@@ -47,4 +143,4 @@ export function buildSelectSql(table, { wheres = [], orders = [], limitValue, of
   }
 
   return { sql, params };
-}
+}

package/src/query/types.d.ts

@@ -1,7 +1,21 @@
-// src/query/types.d.ts
+export type ComparisonOperator =
+  | '='
+  | '!='
+  | '<>'
+  | '>'
+  | '<'
+  | '>='
+  | '<='
+  | 'LIKE'
+  | 'like'
+
+export type ListOperator = 'IN' | 'NOT IN'
+
+export type NullOperator = 'IS NULL' | 'IS NOT NULL'
+
 export interface WhereClause {
   field: string
-  operator: '=' | '!=' | '>' | '<' | '>=' | '<='
+  operator: ComparisonOperator | ListOperator | NullOperator
   value: unknown
 }
 
@@ -15,4 +29,28 @@ export interface QueryDescriptor {
   orders: OrderClause[]
   limitValue?: number
   offsetValue?: number
+}
+
+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>;
 }