@3lineas/d1-orm 1.0.3 → 1.0.5

package/dist/index.d.mts

@@ -22,49 +22,228 @@ interface D1ExecResult {
     duration: number;
 }
 
+/**
+ * Database connection wrapper for D1.
+ */
 declare class Connection {
+    /**
+     * The underlying D1Database instance.
+     */
     protected db: D1Database;
+    /**
+     * Create a new Connection instance.
+     *
+     * @param database - The D1Database instance.
+     */
     constructor(database: D1Database);
+    /**
+     * 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.
+     */
     select(query: string, bindings?: any[]): Promise<any[]>;
+    /**
+     * Execute an INSERT statement.
+     *
+     * @param query - The SQL query string.
+     * @param bindings - The parameter bindings.
+     * @returns A promise that resolves to true on success.
+     */
     insert(query: string, bindings?: any[]): Promise<boolean>;
+    /**
+     * Execute an UPDATE statement.
+     *
+     * @param query - The SQL query string.
+     * @param bindings - The parameter bindings.
+     * @returns A promise that resolves to true on success.
+     */
     update(query: string, bindings?: any[]): Promise<boolean>;
+    /**
+     * Execute a DELETE statement.
+     *
+     * @param query - The SQL query string.
+     * @param bindings - The parameter bindings.
+     * @returns A promise that resolves to true on success.
+     */
     delete(query: string, bindings?: any[]): Promise<boolean>;
+    /**
+     * 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.
+     */
     statement(query: string, bindings?: any[]): Promise<boolean>;
 }
 
 type D1Value = string | number | boolean | null;
+/**
+ * Fluent Query Builder for D1.
+ */
 declare class QueryBuilder {
+    /**
+     * The database connection.
+     */
     protected connection: Connection;
+    /**
+     * The table to query.
+     */
     protected table: string;
+    /**
+     * The columns to select.
+     */
     protected columns: string[];
+    /**
+     * The where constraints for the query.
+     */
     protected wheres: string[];
+    /**
+     * The bindings for the query.
+     */
     protected bindings: D1Value[];
+    /**
+     * The orderings for the query.
+     */
     protected orders: string[];
+    /**
+     * The maximum number of records to return.
+     */
     protected limitValue: number | null;
+    /**
+     * The number of records to skip.
+     */
     protected offsetValue: number | null;
+    /**
+     * Create a new QueryBuilder instance.
+     *
+     * @param connection - The connection instance.
+     * @param table - The table name.
+     */
     constructor(connection: Connection, table: string);
+    /**
+     * Add a SELECT clause to the query.
+     *
+     * @param columns - The columns to select.
+     * @returns The QueryBuilder instance.
+     */
     select(...columns: string[]): 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: string, operator: string, value?: D1Value): 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: string, operator: string, value?: D1Value): 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: string, direction?: "asc" | "desc"): this;
+    /**
+     * Add a LIMIT clause to the query.
+     *
+     * @param limit - The limit value.
+     * @returns The QueryBuilder instance.
+     */
     limit(limit: number): this;
+    /**
+     * Add an OFFSET clause to the query.
+     *
+     * @param offset - The offset value.
+     * @returns The QueryBuilder instance.
+     */
     offset(offset: number): this;
+    /**
+     * Get the SQL representation of the query.
+     *
+     * @returns An object containing the SQL string and the bindings.
+     */
     toSql(): {
         sql: string;
         bindings: D1Value[];
     };
+    /**
+     * Execute the query and get the results.
+     *
+     * @returns A promise that resolves to an array of records.
+     */
     get<T = any>(): Promise<T[]>;
+    /**
+     * Execute the query and get the first result.
+     *
+     * @returns A promise that resolves to the first record or null.
+     */
     first<T = any>(): Promise<T | null>;
+    /**
+     * Insert a new record into the database.
+     *
+     * @param data - The data to insert.
+     * @returns A promise that resolves to true on success.
+     */
     insert(data: Record<string, D1Value>): Promise<boolean>;
+    /**
+     * Update records in the database.
+     *
+     * @param data - The data to update.
+     * @returns A promise that resolves to true on success.
+     */
     update(data: Record<string, D1Value>): Promise<boolean>;
+    /**
+     * Delete records from the database.
+     *
+     * @returns A promise that resolves to true on success.
+     */
     delete(): Promise<boolean>;
 }
 
+/**
+ * Database manager for D1 ORM.
+ *
+ * Handles singleton instance and connection setup.
+ */
 declare class Database {
+    /**
+     * The singleton instance of the Database.
+     */
     private static instance;
+    /**
+     * The active database connection.
+     */
     connection: Connection;
+    /**
+     * Private constructor to enforce singleton pattern.
+     *
+     * @param d1 - The D1Database instance from Cloudflare.
+     */
     private constructor();
+    /**
+     * Setup the database connection.
+     *
+     * @param d1 - The D1Database instance from Cloudflare environment (env.DB).
+     */
     static setup(d1: D1Database): void;
+    /**
+     * Get the singleton Database instance.
+     *
+     * @throws Error if setup() has not been called.
+     * @returns The Database instance.
+     */
     static getInstance(): Database;
 }
 
@@ -99,51 +278,251 @@ declare class BelongsTo<Related extends Model> extends Relationship<Related> {
     addConstraints(): void;
 }
 
+/**
+ * Base Model class for D1 ORM.
+ *
+ * Provides Eloquent-like features for interacting with Cloudflare D1.
+ */
 declare class Model {
+    /**
+     * The table associated with the model.
+     */
     protected static table: string;
+    /**
+     * Resolver function for the database connection.
+     */
     protected static connectionResolver: () => Database;
+    /**
+     * The model's attributes.
+     */
     attributes: Record<string, D1Value>;
+    /**
+     * The attributes that are mass assignable.
+     */
     protected fillable: string[];
+    /**
+     * The attributes that should be hidden for serialization.
+     */
     protected hidden: string[];
+    /**
+     * Indicates if the model exists in the database.
+     */
     exists: boolean;
+    /**
+     * The model's original attribute values.
+     */
     protected original: Record<string, D1Value>;
+    /**
+     * Create a new Model instance.
+     *
+     * @param attributes - Initial attributes for the model.
+     */
     constructor(attributes?: Record<string, D1Value>);
+    /**
+     * Begin querying the model.
+     *
+     * @returns A new ModelQueryBuilder instance.
+     */
     static query<T extends Model>(this: new () => T): ModelQueryBuilder<T>;
+    /**
+     * 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?: string): ModelQueryBuilder<Model>;
+    /**
+     * Retrieve all records for the model.
+     *
+     * @returns A promise that resolves to an array of model instances.
+     */
     static all<T extends Model>(this: new () => T): Promise<T[]>;
+    /**
+     * 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 find<T extends Model>(this: new () => T, id: number | string): Promise<T | null>;
+    /**
+     * 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 create<T extends Model>(this: new () => T, attributes: Record<string, D1Value>): Promise<T>;
+    /**
+     * Fill the model with an array of attributes.
+     *
+     * @param attributes - Attributes to fill.
+     * @returns The model instance.
+     */
     fill(attributes: Record<string, D1Value>): this;
+    /**
+     * Save the model to the database.
+     *
+     * @returns A promise that resolves to true on success, false otherwise.
+     */
     save(): Promise<boolean>;
+    /**
+     * Delete the model from the database.
+     *
+     * @returns A promise that resolves to true on success, false otherwise.
+     */
     delete(): Promise<boolean>;
+    /**
+     * Get the table associated with the model.
+     *
+     * @returns The table name.
+     */
     getTable(): string;
+    /**
+     * Get the attributes that have been changed since the last sync.
+     *
+     * @returns A record of dirty attributes.
+     */
     getDirty(): Record<string, D1Value>;
+    /**
+     * Sync the original attributes with the current attributes.
+     */
     syncOriginal(): void;
+    /**
+     * 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 extends Model>(related: new () => Related, foreignKey?: string, localKey?: string): HasOne<Related>;
+    /**
+     * 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 extends Model>(related: new () => Related, foreignKey?: string, localKey?: string): HasMany<Related>;
+    /**
+     * 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 extends Model>(related: new () => Related, foreignKey?: string, ownerKey?: string): BelongsTo<Related>;
+    /**
+     * Get the default foreign key name for the model.
+     *
+     * @returns The foreign key name.
+     */
     getForeignKey(): string;
+    /**
+     * Get a new query builder for the model's table.
+     *
+     * @returns A ModelQueryBuilder instance.
+     */
     newQuery<T extends Model>(this: T): ModelQueryBuilder<T>;
 }
 
+/**
+ * Specialized Query Builder for Models.
+ *
+ * Automatically maps raw results to Model instances.
+ */
 declare class ModelQueryBuilder<T extends Model> extends QueryBuilder {
+    /**
+     * The class of the model being queried.
+     */
     protected modelClass: typeof Model;
+    /**
+     * 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: any, table: string, modelClass: typeof Model);
+    /**
+     * Execute the query and return model instances.
+     *
+     * @returns A promise that resolves to an array of model instances.
+     */
     get<M = T>(): Promise<M[]>;
+    /**
+     * Execute the query and return the first matching model instance.
+     *
+     * @returns A promise that resolves to the model instance or null.
+     */
     first<M = T>(): Promise<M | null>;
+    /**
+     * Get the underlying model class.
+     *
+     * @returns The model class constructor.
+     */
     getModel(): typeof Model;
 }
 
+/**
+ * Represents a database column definition.
+ */
+declare class Column {
+    protected name: string;
+    protected type: string;
+    protected isNullable: boolean;
+    protected isUnique: boolean;
+    protected defaultValue: any;
+    constructor(name: string, type: string);
+    /**
+     * Set the column as nullable.
+     */
+    nullable(): this;
+    /**
+     * Set the column as unique.
+     */
+    unique(): this;
+    /**
+     * Set the default value for the column.
+     */
+    default(value: any): this;
+    /**
+     * Convert the column definition to SQL.
+     */
+    toSql(): string;
+}
+/**
+ * Schema Blueprint for defining tables.
+ */
 declare class Blueprint {
     protected table: string;
-    protected columns: string[];
+    protected columns: (Column | string)[];
     protected commands: string[];
     constructor(table: string);
+    /**
+     * Add an auto-incrementing ID column.
+     */
     id(): this;
-    string(column: string, length?: number): this;
-    integer(column: string): this;
-    boolean(column: string): this;
+    /**
+     * Add a string (TEXT) column.
+     */
+    string(column: string): Column;
+    /**
+     * Add an integer column.
+     */
+    integer(column: string): Column;
+    /**
+     * Add a boolean column.
+     */
+    boolean(column: string): Column;
+    /**
+     * Add created_at and updated_at timestamp columns.
+     */
     timestamps(): this;
+    /**
+     * Convert the blueprint to a set of SQL statements.
+     */
     toSql(): string[];
 }
 
@@ -152,4 +531,4 @@ declare class Schema {
     static dropIfExists(table: string): string;
 }
 
-export { BelongsTo, Blueprint, Connection, type D1Database, type D1ExecResult, type D1PreparedStatement, type D1Result, type D1Value, Database, HasMany, HasOne, Model, ModelQueryBuilder, QueryBuilder, Relationship, Schema };
+export { BelongsTo, Blueprint, Column, Connection, type D1Database, type D1ExecResult, type D1PreparedStatement, type D1Result, type D1Value, Database, HasMany, HasOne, Model, ModelQueryBuilder, QueryBuilder, Relationship, Schema };