d1mapper/dist/Database.d.ts

A simple ORM-like wrapper for Cloudflare D1 databases in TypeScript

import { D1Database } from '@cloudflare/workers-types';
/**
 * The result of a database operation.
 */
export interface DatabaseResult {
    success: boolean;
    changes?: number;
}
/**
 * Options for constructing a Database instance.
 * @template T - Record type representing table schema.
 */
export interface DatabaseOptions<T extends Record<string, any>> {
    db: D1Database;
    tableName: string;
    defaultProperties?: Partial<T>;
    primaryKeyName: keyof T;
}
/**
 * A wrapper around Cloudflare D1 providing basic CRUD operations.
 * @template T - Record type representing table schema.
 */
export declare class Database<T extends Record<string, any>> {
    db: D1Database;
    tableName: string;
    defaultProperties: Partial<T>;
    primaryKeyName: keyof T;
    /**
     * Construct a Database instance.
     * @param options - Options for the database instance.
     */
    constructor(options: DatabaseOptions<T>);
    /**
     * Execute a SQL query with positional parameters.
     * @param query - SQL query string.
     * @param params - Array of parameters to bind.
     * @returns DatabaseResult containing success status and change count.
     */
    private exec;
    /**
     * Insert a record into the table. Missing props use defaults.
     * @param record - Partial record to insert.
     * @param inPlaceModify - Whether to modify the record in place (default true).
     * @returns Result of the insert operation.
     */
    insert(record: Partial<T>, inPlaceModify?: boolean): Promise<DatabaseResult>;
    /**
     * Find one record matching a condition and return the full record.
     *
     * @param props - An empty array indicating all columns should be selected (`SELECT *`).
     * @param conditionKey - Column to filter by.
     * @param conditionValue - Value to match.
     * @returns The full record (`T`) if found, or null.
     */
    findOne(props: [], conditionKey: keyof T, conditionValue: T[keyof T]): Promise<T | null>;
    /**
     * Find one record matching a condition and select specific columns.
     *
     * @param props - Column(s) to select.
     * @param conditionKey - Column to filter by.
     * @param conditionValue - Value to match.
     * @returns The record with selected properties if found, or null.
     */
    findOne<K extends keyof T>(props: K | K[], conditionKey: keyof T, conditionValue: T[keyof T]): Promise<Pick<T, K> | null>;
    /**
     * Retrieve all records with all columns.
     *
     * @param props - An empty array indicating all columns should be selected (`SELECT *`).
     * @param paginationOptions - (optional) Object containing `limit` and `offset` properties for pagination.
     * @returns Array of full records (`T[]`).
     */
    findAll(props: [], paginationOptions?: {
        limit?: number;
        offset?: number;
    }): Promise<T[]>;
    /**
     * Retrieve all records with selected properties.
     *
     * @param props - Column(s) to select.
     * @param paginationOptions - (optional) Object containing `limit` and `offset` properties for pagination.
     * @returns Array of records with selected properties.
     */
    findAll<K extends keyof T>(props: K | K[], paginationOptions?: {
        limit?: number;
        offset?: number;
    }): Promise<Pick<T, K>[]>;
    /**
     * Find records matching a filter (all columns).
     * @param props - An empty array indicating all columns should be selected (`SELECT *`).
     * @param filter - Partial record for WHERE clause.
     * @param paginationOptions - (optional) Object containing `limit` and `offset` properties for pagination.
     */
    findMany(props: [], filter: Partial<T>, paginationOptions?: {
        limit?: number;
        offset?: number;
    }): Promise<T[]>;
    /**
     * Find records matching a filter with selected properties.
     * @param props - Column(s) to select.
     * @param filter - Partial record for WHERE clause.
     * @param paginationOptions - (optional) Object containing `limit` and `offset` properties for pagination.
     */
    findMany<K extends keyof T>(props: K | K[], filter: Partial<T>, paginationOptions?: {
        limit?: number;
        offset?: number;
    }): Promise<Pick<T, K>[]>;
    /**
     * Update records matching a condition.
     * @param record - Partial properties to update.
     * @param conditionKey - Column to filter by.
     * @param conditionValue - Value to match.
     * @returns Result containing change count.
     */
    update(record: Partial<T>, conditionKey: keyof T, conditionValue: T[keyof T]): Promise<DatabaseResult>;
    /**
     * Delete records matching a condition.
     * @param conditionKey - Column to filter by.
     * @param conditionValue - Value to match.
     * @returns Result containing change count.
     */
    delete(conditionKey: keyof T, conditionValue: T[keyof T]): Promise<DatabaseResult>;
    /**
     * Increment a numeric column by a step for matching records.
     * @param column - Column to increment.
     * @param step - Amount to add.
     * @param conditionKey - Column to filter by.
     * @param conditionValue - Value to match.
     * @returns Result containing change count.
     */
    increment(column: keyof T, step: number, conditionKey: keyof T, conditionValue: T[keyof T]): Promise<DatabaseResult>;
    /**
     * Check existence of a record matching a condition.
     * @param conditionKey - Column to filter by.
     * @param conditionValue - Value to match.
     * @returns True if record exists, else false.
     */
    exists(conditionKey: keyof T, conditionValue: T[keyof T]): Promise<boolean>;
    /**
     * Find a record by primary key returning full record.
     * @param props - An empty array to select all columns.
     * @param id - Primary key value.
     */
    findById<K extends keyof T>(props: [], id: T[keyof T]): Promise<T | null>;
    /**
       * Find a record by primary key.
       * @param props - Column(s) to select.
       * @param id - Primary key value.
       */
    findById<K extends keyof T>(props: K | K[], id: T[keyof T]): Promise<Pick<T, K> | null>;
    /**
     * Update a record by primary key.
     * @param record - Partial properties to update.
     * @param id - Primary key value.
     */
    updateById(record: Partial<T>, id: T[keyof T]): Promise<DatabaseResult>;
    /**
     * Delete a record by primary key.
     * @param id - Primary key value.
     */
    deleteById(id: T[keyof T]): Promise<DatabaseResult>;
    /**
     * Increment a numeric column by primary key.
     * @param column - Column to increment.
     * @param step - Amount to add.
     * @param id - Primary key value.
     */
    incrementById(column: keyof T, step: number, id: T[keyof T]): Promise<DatabaseResult>;
    /**
     * Check existence by primary key.
     * @param id - Primary key value.
     */
    existsById(id: T[keyof T]): Promise<boolean>;
}