@3lineas/d1-orm 1.0.3 → 1.0.4

package/dist/index.js

@@ -36,30 +36,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 +112,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 +181,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 +198,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 +254,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 +286,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 +303,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 +326,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 +356,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 +378,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 +492,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 +611,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 +624,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,31 +649,67 @@ 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();
   }