@3lineas/d1-orm 1.0.3 → 1.0.5

package/dist/index.js

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   BelongsTo: () => BelongsTo,
   Blueprint: () => Blueprint,
+  Column: () => Column,
   Connection: () => Connection,
   Database: () => Database,
   HasMany: () => HasMany,
@@ -36,30 +37,73 @@ module.exports = __toCommonJS(index_exports);
 
 // src/core/connection.ts
 var Connection = class {
+  /**
+   * The underlying D1Database instance.
+   */
   db;
+  /**
+   * Create a new Connection instance.
+   *
+   * @param database - The D1Database instance.
+   */
   constructor(database) {
     this.db = database;
   }
+  /**
+   * Execute a SELECT statement.
+   *
+   * @param query - The SQL query string.
+   * @param bindings - The parameter bindings.
+   * @returns A promise that resolves to an array of results.
+   */
   async select(query, bindings = []) {
     const stmt = this.db.prepare(query).bind(...bindings);
     const result = await stmt.all();
     return result.results || [];
   }
+  /**
+   * Execute an INSERT statement.
+   *
+   * @param query - The SQL query string.
+   * @param bindings - The parameter bindings.
+   * @returns A promise that resolves to true on success.
+   */
   async insert(query, bindings = []) {
     const stmt = this.db.prepare(query).bind(...bindings);
     const result = await stmt.run();
     return result.success;
   }
+  /**
+   * Execute an UPDATE statement.
+   *
+   * @param query - The SQL query string.
+   * @param bindings - The parameter bindings.
+   * @returns A promise that resolves to true on success.
+   */
   async update(query, bindings = []) {
     const stmt = this.db.prepare(query).bind(...bindings);
     const result = await stmt.run();
     return result.success;
   }
+  /**
+   * Execute a DELETE statement.
+   *
+   * @param query - The SQL query string.
+   * @param bindings - The parameter bindings.
+   * @returns A promise that resolves to true on success.
+   */
   async delete(query, bindings = []) {
     const stmt = this.db.prepare(query).bind(...bindings);
     const result = await stmt.run();
     return result.success;
   }
+  /**
+   * Execute an arbitrary SQL statement.
+   *
+   * @param query - The SQL query string.
+   * @param bindings - The parameter bindings.
+   * @returns A promise that resolves to true on success.
+   */
   async statement(query, bindings = []) {
     const stmt = this.db.prepare(query).bind(...bindings);
     const result = await stmt.run();
@@ -69,22 +113,66 @@ var Connection = class {
 
 // src/core/query-builder.ts
 var QueryBuilder = class {
+  /**
+   * The database connection.
+   */
   connection;
+  /**
+   * The table to query.
+   */
   table;
+  /**
+   * The columns to select.
+   */
   columns = ["*"];
+  /**
+   * The where constraints for the query.
+   */
   wheres = [];
+  /**
+   * The bindings for the query.
+   */
   bindings = [];
+  /**
+   * The orderings for the query.
+   */
   orders = [];
+  /**
+   * The maximum number of records to return.
+   */
   limitValue = null;
+  /**
+   * The number of records to skip.
+   */
   offsetValue = null;
+  /**
+   * Create a new QueryBuilder instance.
+   *
+   * @param connection - The connection instance.
+   * @param table - The table name.
+   */
   constructor(connection, table) {
     this.connection = connection;
     this.table = table;
   }
+  /**
+   * Add a SELECT clause to the query.
+   *
+   * @param columns - The columns to select.
+   * @returns The QueryBuilder instance.
+   */
   select(...columns) {
     this.columns = columns.length > 0 ? columns : ["*"];
     return this;
   }
+  /**
+   * Add a basic WHERE clause to the query.
+   *
+   * @param column - The column name.
+   * @param operator - The operator or value.
+   * @param value - The value if operator is provided.
+   * @returns The QueryBuilder instance.
+   */
   where(column, operator, value) {
     if (value === void 0) {
       value = operator;
@@ -94,6 +182,14 @@ var QueryBuilder = class {
     this.bindings.push(value);
     return this;
   }
+  /**
+   * Add an OR WHERE clause to the query.
+   *
+   * @param column - The column name.
+   * @param operator - The operator or value.
+   * @param value - The value if operator is provided.
+   * @returns The QueryBuilder instance.
+   */
   orWhere(column, operator, value) {
     if (value === void 0) {
       value = operator;
@@ -103,18 +199,42 @@ var QueryBuilder = class {
     this.bindings.push(value);
     return this;
   }
+  /**
+   * Add an ORDER BY clause to the query.
+   *
+   * @param column - The column name.
+   * @param direction - The direction of the order.
+   * @returns The QueryBuilder instance.
+   */
   orderBy(column, direction = "asc") {
     this.orders.push(`${column} ${direction.toUpperCase()}`);
     return this;
   }
+  /**
+   * Add a LIMIT clause to the query.
+   *
+   * @param limit - The limit value.
+   * @returns The QueryBuilder instance.
+   */
   limit(limit) {
     this.limitValue = limit;
     return this;
   }
+  /**
+   * Add an OFFSET clause to the query.
+   *
+   * @param offset - The offset value.
+   * @returns The QueryBuilder instance.
+   */
   offset(offset) {
     this.offsetValue = offset;
     return this;
   }
+  /**
+   * Get the SQL representation of the query.
+   *
+   * @returns An object containing the SQL string and the bindings.
+   */
   toSql() {
     let sql = `SELECT ${this.columns.join(", ")} FROM ${this.table}`;
     if (this.wheres.length > 0) {
@@ -135,15 +255,31 @@ var QueryBuilder = class {
     }
     return { sql, bindings: this.bindings };
   }
+  /**
+   * Execute the query and get the results.
+   *
+   * @returns A promise that resolves to an array of records.
+   */
   async get() {
     const { sql, bindings } = this.toSql();
     return this.connection.select(sql, bindings);
   }
+  /**
+   * Execute the query and get the first result.
+   *
+   * @returns A promise that resolves to the first record or null.
+   */
   async first() {
     this.limit(1);
     const results = await this.get();
     return results.length > 0 ? results[0] : null;
   }
+  /**
+   * Insert a new record into the database.
+   *
+   * @param data - The data to insert.
+   * @returns A promise that resolves to true on success.
+   */
   async insert(data) {
     const columns = Object.keys(data);
     const values = Object.values(data);
@@ -151,6 +287,12 @@ var QueryBuilder = class {
     const sql = `INSERT INTO ${this.table} (${columns.join(", ")}) VALUES (${placeholders})`;
     return this.connection.insert(sql, values);
   }
+  /**
+   * Update records in the database.
+   *
+   * @param data - The data to update.
+   * @returns A promise that resolves to true on success.
+   */
   async update(data) {
     const columns = Object.keys(data);
     const values = Object.values(data);
@@ -162,10 +304,14 @@ var QueryBuilder = class {
         return w.startsWith("OR") ? w : `AND ${w}`;
       });
       sql += ` WHERE ${constraints.join(" ")}`;
-    } else {
     }
     return this.connection.update(sql, [...values, ...this.bindings]);
   }
+  /**
+   * Delete records from the database.
+   *
+   * @returns A promise that resolves to true on success.
+   */
   async delete() {
     let sql = `DELETE FROM ${this.table}`;
     if (this.wheres.length > 0) {
@@ -181,11 +327,26 @@ var QueryBuilder = class {
 
 // src/core/model-query-builder.ts
 var ModelQueryBuilder = class extends QueryBuilder {
+  /**
+   * The class of the model being queried.
+   */
   modelClass;
+  /**
+   * Create a new ModelQueryBuilder instance.
+   *
+   * @param connection - The database connection.
+   * @param table - The table name.
+   * @param modelClass - The class constructor for the model.
+   */
   constructor(connection, table, modelClass) {
     super(connection, table);
     this.modelClass = modelClass;
   }
+  /**
+   * Execute the query and return model instances.
+   *
+   * @returns A promise that resolves to an array of model instances.
+   */
   async get() {
     const { sql, bindings } = this.toSql();
     const results = await this.connection.select(sql, bindings);
@@ -196,11 +357,21 @@ var ModelQueryBuilder = class extends QueryBuilder {
       return instance;
     });
   }
+  /**
+   * Execute the query and return the first matching model instance.
+   *
+   * @returns A promise that resolves to the model instance or null.
+   */
   async first() {
     this.limit(1);
     const results = await this.get();
     return results.length > 0 ? results[0] : null;
   }
+  /**
+   * Get the underlying model class.
+   *
+   * @returns The model class constructor.
+   */
   getModel() {
     return this.modelClass;
   }
@@ -208,14 +379,36 @@ var ModelQueryBuilder = class extends QueryBuilder {
 
 // src/core/database.ts
 var Database = class _Database {
+  /**
+   * The singleton instance of the Database.
+   */
   static instance;
+  /**
+   * The active database connection.
+   */
   connection;
+  /**
+   * Private constructor to enforce singleton pattern.
+   *
+   * @param d1 - The D1Database instance from Cloudflare.
+   */
   constructor(d1) {
     this.connection = new Connection(d1);
   }
+  /**
+   * Setup the database connection.
+   *
+   * @param d1 - The D1Database instance from Cloudflare environment (env.DB).
+   */
   static setup(d1) {
     _Database.instance = new _Database(d1);
   }
+  /**
+   * Get the singleton Database instance.
+   *
+   * @throws Error if setup() has not been called.
+   * @returns The Database instance.
+   */
   static getInstance() {
     if (!_Database.instance) {
       throw new Error(
@@ -300,43 +493,106 @@ var BelongsTo = class extends Relationship {
 
 // src/models/model.ts
 var Model = class {
+  /**
+   * The table associated with the model.
+   */
   static table;
+  /**
+   * Resolver function for the database connection.
+   */
   static connectionResolver;
+  /**
+   * The model's attributes.
+   */
   attributes = {};
+  /**
+   * The attributes that are mass assignable.
+   */
   fillable = [];
+  /**
+   * The attributes that should be hidden for serialization.
+   */
   hidden = [];
+  /**
+   * Indicates if the model exists in the database.
+   */
   exists = false;
+  /**
+   * The model's original attribute values.
+   */
   original = {};
+  /**
+   * Create a new Model instance.
+   *
+   * @param attributes - Initial attributes for the model.
+   */
   constructor(attributes = {}) {
     this.fill(attributes);
   }
-  // Static Query Builder
+  /**
+   * Begin querying the model.
+   *
+   * @returns A new ModelQueryBuilder instance.
+   */
   static query() {
     const instance = new this();
     const table = instance.getTable();
     const connection = Database.getInstance().connection;
     return new ModelQueryBuilder(connection, table, this);
   }
+  /**
+   * Start a query on a specific connection (currently uses default).
+   *
+   * @param connectionName - The name of the connection.
+   * @returns A new ModelQueryBuilder instance.
+   */
   static on(connectionName) {
     return this.query();
   }
+  /**
+   * Retrieve all records for the model.
+   *
+   * @returns A promise that resolves to an array of model instances.
+   */
   static async all() {
     return this.query().get();
   }
+  /**
+   * Find a model by its primary key.
+   *
+   * @param id - The ID of the record.
+   * @returns A promise that resolves to the model instance or null if not found.
+   */
   static async find(id) {
     return this.query().where("id", "=", id).first();
   }
+  /**
+   * Save a new model and return the instance.
+   *
+   * @param attributes - Attributes for the new record.
+   * @returns A promise that resolves to the created model instance.
+   */
   static async create(attributes) {
     const instance = new this();
     instance.fill(attributes);
     await instance.save();
     return instance;
   }
-  // Instance Methods
+  /**
+   * Fill the model with an array of attributes.
+   *
+   * @param attributes - Attributes to fill.
+   * @returns The model instance.
+   */
   fill(attributes) {
     Object.assign(this.attributes, attributes);
     return this;
   }
+  /**
+   * Save the model to the database.
+   *
+   * @returns A promise that resolves to true on success, false otherwise.
+   */
   async save() {
     const query = this.constructor.query();
     if (this.exists) {
@@ -356,6 +612,11 @@ var Model = class {
       return false;
     }
   }
+  /**
+   * Delete the model from the database.
+   *
+   * @returns A promise that resolves to true on success, false otherwise.
+   */
   async delete() {
     if (!this.exists) return false;
     const query = this.constructor.query();
@@ -364,12 +625,22 @@ var Model = class {
     this.exists = false;
     return true;
   }
+  /**
+   * Get the table associated with the model.
+   *
+   * @returns The table name.
+   */
   getTable() {
     if (this.constructor.table) {
       return this.constructor.table;
     }
     return this.constructor.name.toLowerCase() + "s";
   }
+  /**
+   * Get the attributes that have been changed since the last sync.
+   *
+   * @returns A record of dirty attributes.
+   */
   getDirty() {
     const dirty = {};
     for (const key in this.attributes) {
@@ -379,37 +650,122 @@ var Model = class {
     }
     return dirty;
   }
+  /**
+   * Sync the original attributes with the current attributes.
+   */
   syncOriginal() {
     this.original = { ...this.attributes };
   }
-  // Relationships
+  /**
+   * Define a one-to-one relationship.
+   *
+   * @param related - The related model class.
+   * @param foreignKey - The foreign key on the related table.
+   * @param localKey - The local key on the current table.
+   * @returns A HasOne relationship instance.
+   */
   hasOne(related, foreignKey, localKey) {
     const instance = new related();
     const fk = foreignKey || this.getForeignKey();
     const lk = localKey || "id";
     return new HasOne(instance.newQuery(), this, fk, lk);
   }
+  /**
+   * Define a one-to-many relationship.
+   *
+   * @param related - The related model class.
+   * @param foreignKey - The foreign key on the related table.
+   * @param localKey - The local key on the current table.
+   * @returns A HasMany relationship instance.
+   */
   hasMany(related, foreignKey, localKey) {
     const instance = new related();
     const fk = foreignKey || this.getForeignKey();
     const lk = localKey || "id";
     return new HasMany(instance.newQuery(), this, fk, lk);
   }
+  /**
+   * Define an inverse one-to-one or many relationship.
+   *
+   * @param related - The related model class.
+   * @param foreignKey - The foreign key on the current table.
+   * @param ownerKey - The owner key on the related table.
+   * @returns A BelongsTo relationship instance.
+   */
   belongsTo(related, foreignKey, ownerKey) {
     const instance = new related();
     const fk = foreignKey || instance.getForeignKey();
     const ok = ownerKey || "id";
     return new BelongsTo(instance.newQuery(), this, fk, ok);
   }
+  /**
+   * Get the default foreign key name for the model.
+   *
+   * @returns The foreign key name.
+   */
   getForeignKey() {
     return this.getTable().slice(0, -1) + "_id";
   }
+  /**
+   * Get a new query builder for the model's table.
+   *
+   * @returns A ModelQueryBuilder instance.
+   */
   newQuery() {
     return this.constructor.query();
   }
 };
 
 // src/database/blueprint.ts
+var Column = class {
+  name;
+  type;
+  isNullable = false;
+  isUnique = false;
+  defaultValue = null;
+  constructor(name, type) {
+    this.name = name;
+    this.type = type;
+  }
+  /**
+   * Set the column as nullable.
+   */
+  nullable() {
+    this.isNullable = true;
+    return this;
+  }
+  /**
+   * Set the column as unique.
+   */
+  unique() {
+    this.isUnique = true;
+    return this;
+  }
+  /**
+   * Set the default value for the column.
+   */
+  default(value) {
+    this.defaultValue = value;
+    return this;
+  }
+  /**
+   * Convert the column definition to SQL.
+   */
+  toSql() {
+    let sql = `${this.name} ${this.type}`;
+    if (this.isUnique) {
+      sql += " UNIQUE";
+    }
+    if (!this.isNullable) {
+      sql += " NOT NULL";
+    }
+    if (this.defaultValue !== null) {
+      const formattedValue = typeof this.defaultValue === "string" ? `'${this.defaultValue}'` : this.defaultValue;
+      sql += ` DEFAULT ${formattedValue}`;
+    }
+    return sql;
+  }
+};
 var Blueprint = class {
   table;
   columns = [];
@@ -417,30 +773,55 @@ var Blueprint = class {
   constructor(table) {
     this.table = table;
   }
+  /**
+   * Add an auto-incrementing ID column.
+   */
   id() {
     this.columns.push("id INTEGER PRIMARY KEY AUTOINCREMENT");
     return this;
   }
-  string(column, length) {
-    this.columns.push(`${column} TEXT`);
-    return this;
-  }
+  /**
+   * Add a string (TEXT) column.
+   */
+  string(column) {
+    const col = new Column(column, "TEXT");
+    this.columns.push(col);
+    return col;
+  }
+  /**
+   * Add an integer column.
+   */
   integer(column) {
-    this.columns.push(`${column} INTEGER`);
-    return this;
+    const col = new Column(column, "INTEGER");
+    this.columns.push(col);
+    return col;
   }
+  /**
+   * Add a boolean column.
+   */
   boolean(column) {
-    this.columns.push(`${column} BOOLEAN`);
-    return this;
+    const col = new Column(column, "BOOLEAN");
+    this.columns.push(col);
+    return col;
   }
+  /**
+   * Add created_at and updated_at timestamp columns.
+   */
   timestamps() {
     this.columns.push("created_at DATETIME DEFAULT CURRENT_TIMESTAMP");
     this.columns.push("updated_at DATETIME DEFAULT CURRENT_TIMESTAMP");
     return this;
   }
+  /**
+   * Convert the blueprint to a set of SQL statements.
+   */
   toSql() {
     if (this.columns.length > 0) {
-      const cols = this.columns.join(", ");
+      const colDefinitions = this.columns.map((col) => {
+        if (typeof col === "string") return col;
+        return col.toSql();
+      });
+      const cols = colDefinitions.join(", ");
       return [`CREATE TABLE IF NOT EXISTS ${this.table} (${cols})`];
     }
     return this.commands;
@@ -462,6 +843,7 @@ var Schema = class {
 0 && (module.exports = {
   BelongsTo,
   Blueprint,
+  Column,
   Connection,
   Database,
   HasMany,