@hedystia/db 2.0.3 → 2.0.5

package/dist/types.d.mts

@@ -1,5 +1,10 @@
 //#region src/types.d.ts
-type ColumnDataType = "integer" | "varchar" | "text" | "boolean" | "json" | "datetime" | "decimal" | "float" | "char" | "timestamp" | "bigint" | "blob";
+/** Supported column data types for schema definitions */
+type ColumnDataType = "integer" | "varchar" | "text" | "boolean" | "json" | "array" | "datetime" | "decimal" | "float" | "char" | "timestamp" | "bigint" | "blob";
+/**
+ * Database type identifier — can be a simple string shorthand or an object
+ * specifying both the database name and the driver provider to use
+ */
 type DatabaseType = "mysql" | "mariadb" | "sqlite" | "file" | {
   name: "mysql";
   provider: "mysql" | "mysql2";
@@ -13,18 +18,31 @@ type DatabaseType = "mysql" | "mariadb" | "sqlite" | "file" | {
   name: "file";
   provider: string;
 };
+/** Metadata describing a single database column */
 interface ColumnMetadata {
+  /** Column name in the database */
   name: string;
+  /** Data type of the column */
   type: ColumnDataType;
+  /** Whether this column is a primary key */
   primaryKey: boolean;
+  /** Whether this column auto-increments */
   autoIncrement: boolean;
+  /** Whether this column disallows NULL values */
   notNull: boolean;
+  /** Whether this column has a UNIQUE constraint */
   unique: boolean;
+  /** Default value for the column, or `undefined` if none */
   defaultValue: unknown;
+  /** Maximum character length (for varchar/char types) */
   length?: number;
+  /** Total number of digits (for decimal types) */
   precision?: number;
+  /** Number of decimal digits (for decimal types) */
   scale?: number;
+  /** Custom database column name alias, if different from the property key */
   columnAlias?: string;
+  /** Foreign key reference metadata, resolved after registration */
   references?: {
     table: string;
     column: string;
@@ -33,11 +51,16 @@ interface ColumnMetadata {
     relationName?: string;
   };
 }
+/** Action to take when a referenced row is deleted or updated */
 type ReferenceAction = "CASCADE" | "SET NULL" | "RESTRICT" | "NO ACTION";
+/** Metadata describing a database table and its columns */
 interface TableMetadata {
+  /** Table name in the database */
   name: string;
+  /** Array of column metadata for this table */
   columns: ColumnMetadata[];
 }
+/** Deferred foreign key reference metadata, used internally for lazy resolution */
 type DeferredRefMeta<ColumnName extends string = string, TargetTable extends string = string, TargetColumn extends string = string, RelationName extends string | undefined = string | undefined> = {
   columnName: ColumnName;
   targetTable: TargetTable;
@@ -46,6 +69,10 @@ type DeferredRefMeta<ColumnName extends string = string, TargetTable extends str
   onDelete?: ReferenceAction;
   onUpdate?: ReferenceAction;
 };
+/**
+ * Internal representation of a table schema, including column metadata,
+ * deferred references, and optional per-table cache configuration
+ */
 type TableDefinition<T extends Record<string, any> = Record<string, any>, C extends Record<string, any> = {}, N extends string = string, Refs extends DeferredRefMeta = any> = {
   __table: true;
   __name: N;
@@ -53,6 +80,7 @@ type TableDefinition<T extends Record<string, any> = Record<string, any>, C exte
   __refs: Refs;
   __columns: ColumnMetadata[];
   __columnMap: Record<string, string>;
+  __cache?: TableCacheConfig;
   __deferredRefs: Array<{
     columnName: string;
     resolve: () => {
@@ -64,12 +92,16 @@ type TableDefinition<T extends Record<string, any> = Record<string, any>, C exte
     relationName?: string;
   }>;
 } & C;
+/** Extract the row type from a table definition */
 type InferRow<T> = T extends {
   __row: infer R;
 } ? R : never;
+/** Extract the insertable type from a table definition (auto-increment keys become optional) */
 type InferInsert<T> = T extends TableDefinition<infer R, any, any> ? { [K in keyof R as K extends AutoIncrementKeys<T> ? never : K]: R[K] } & { [K in AutoIncrementKeys<T>]?: R[K] } : never;
 type AutoIncrementKeys<T> = T extends TableDefinition<infer R, any, any> ? keyof R : never;
+/** Extract the updatable type from a table definition (all fields become optional) */
 type InferUpdate<T> = T extends TableDefinition<infer R, any, any> ? Partial<R> : never;
+/** Condition operators for a single column in a WHERE clause */
 interface WhereCondition {
   eq?: unknown;
   neq?: unknown;
@@ -84,25 +116,38 @@ interface WhereCondition {
   isNull?: boolean;
   between?: [unknown, unknown];
 }
+/** Type-safe WHERE clause supporting equality, operators, and logical combinators (OR/AND) */
 type WhereClause<T = Record<string, any>> = { [K in keyof T]?: T[K] | WhereCondition } & {
   OR?: WhereClause<T>[];
   AND?: WhereClause<T>[];
 };
+/** Options for querying rows — filtering, sorting, pagination, and relation loading */
 interface QueryOptions<T = Record<string, any>, Rel extends Record<string, any> = {}> {
+  /** Filter conditions */
   where?: WhereClause<T>;
+  /** Columns to include in the result */
   select?: Extract<keyof T, string>[];
+  /** Sort order for results */
   orderBy?: Partial<Record<Extract<keyof T, string>, "asc" | "desc">>;
+  /** Maximum number of rows to return */
   take?: number;
+  /** Number of rows to skip (for pagination) */
   skip?: number;
+  /** Related tables to eagerly load */
   with?: { [K in keyof Rel]?: boolean | QueryOptions<Rel[K] extends {
     row: infer R;
   } ? R : Rel[K]> };
 }
+/** Options for an UPDATE operation */
 interface UpdateOptions<T = Record<string, any>> {
+  /** Filter to select which rows to update */
   where: WhereClause<T>;
+  /** Partial data to apply to matching rows */
   data: Partial<T>;
 }
+/** Options for a DELETE operation */
 interface DeleteOptions<T = Record<string, any>> {
+  /** Filter to select which rows to delete */
   where: WhereClause<T>;
 }
 interface MySQLConnectionConfig {
@@ -112,28 +157,81 @@ interface MySQLConnectionConfig {
   password: string;
   database: string;
 }
+/** Connection configuration for SQLite databases */
 interface SQLiteConnectionConfig {
+  /** Path to the SQLite database file */
   filename: string;
 }
+/** Connection configuration for file-based (JSON) storage */
 interface FileConnectionConfig {
+  /** Directory where data files are stored */
   directory: string;
 }
+/** Union of all supported connection configurations */
 type ConnectionConfig = MySQLConnectionConfig | SQLiteConnectionConfig | FileConnectionConfig;
+/**
+ * Global cache configuration for the database instance.
+ * Controls query result caching and entity caching behavior.
+ */
 interface CacheConfig {
+  /** Whether caching is enabled */
   enabled: boolean;
+  /** Base time-to-live in milliseconds (default: 60000) */
   ttl?: number;
+  /** Maximum TTL in milliseconds — limits adaptive TTL scaling (default: 300000) */
   maxTtl?: number;
+  /** Maximum number of cache entries before eviction (default: 10000) */
   maxEntries?: number;
 }
+/**
+ * Per-table cache configuration. Set on individual table definitions to override
+ * or enable caching for specific tables independently of the global setting.
+ * Useful for frequently accessed tables like user sessions or login data.
+ */
+interface TableCacheConfig {
+  /** Whether caching is enabled for this table */
+  enabled: boolean;
+  /** Base time-to-live in milliseconds for this table's cache entries */
+  ttl?: number;
+  /** Maximum TTL in milliseconds for this table's cache entries */
+  maxTtl?: number;
+}
+/**
+ * Top-level configuration for creating a database instance.
+ * Defines schemas, database type, connection, and optional features like
+ * schema sync, migrations, and caching.
+ */
 interface DatabaseConfig {
-  schemas: readonly TableDefinition<any, any, any>[];
-  migrations?: any[];
+  /**
+   * Table definitions — either an array of tables or a module namespace object.
+   * @example
+   * // Array form
+   * schemas: [users, posts]
+   * // Module namespace form (import * as schemas from "./schemas")
+   * schemas: schemas
+   */
+  schemas: readonly AnyTableDef[] | Record<string, unknown>;
+  /**
+   * Migration definitions — either an array of migrations or a module namespace object.
+   * @example
+   * // Array form
+   * migrations: [createUsers, addAge]
+   * // Module namespace form (import * as migrations from "./migrations")
+   * migrations: migrations
+   */
+  migrations?: MigrationDefinition[] | Record<string, unknown>;
+  /** Database type and optional driver provider */
   database: DatabaseType;
+  /** Connection configuration (or array for future multi-connection support) */
   connection: ConnectionConfig | ConnectionConfig[];
+  /** Whether to run pending migrations on initialization */
   runMigrations?: boolean;
+  /** Whether to auto-create tables and add missing columns on initialization */
   syncSchemas?: boolean;
+  /** Enable caching — `true` for defaults, or a {@link CacheConfig} object for fine-tuning */
   cache?: boolean | CacheConfig;
 }
+/** Context object passed to migration up/down functions */
 interface MigrationContext {
   schema: {
     createTable: (table: TableDefinition) => Promise<void>;
@@ -146,11 +244,16 @@ interface MigrationContext {
   };
   sql: (query: string, params?: unknown[]) => Promise<unknown>;
 }
+/** A named migration with up (apply) and down (rollback) functions */
 interface MigrationDefinition {
+  /** Unique migration name (used for tracking executed migrations) */
   name: string;
+  /** Function to apply the migration */
   up: (ctx: MigrationContext) => Promise<void>;
+  /** Function to rollback the migration */
   down: (ctx: MigrationContext) => Promise<void>;
 }
+/** Low-level database driver interface — implemented per database backend */
 interface DatabaseDriver {
   connect(): Promise<void>;
   disconnect(): Promise<void>;
@@ -166,6 +269,7 @@ interface DatabaseDriver {
   transaction<T>(fn: () => Promise<T>): Promise<T>;
   getAllTableColumns?(): Promise<Record<string, ColumnMetadata[]>>;
 }
+/** Generic repository interface providing CRUD operations for a table */
 interface Repository<T extends Record<string, any>> {
   find(options?: QueryOptions<T>): Promise<T[]>;
   findMany(options?: QueryOptions<T>): Promise<T[]>;
@@ -206,6 +310,7 @@ type ReverseRelationEntry<U extends AnyTableDef, TargetName extends string> = Ta
 } } : never : never;
 type ReverseRelationEntries<S extends readonly AnyTableDef[], T extends AnyTableDef> = ReverseRelationEntry<S[number], TableName<T>>;
 type RelationsFor<S extends readonly AnyTableDef[], T extends AnyTableDef> = Simplify<UnionToIntersection<ForwardRelationEntries<S, T> | ReverseRelationEntries<S, T>>>;
+type InferSchemas<T> = T extends readonly AnyTableDef[] ? T : T extends Record<string, any> ? Array<{ [K in keyof T]: T[K] extends AnyTableDef ? T[K] : never }[keyof T]> : readonly AnyTableDef[];
 type DepthPrev = [never, 0, 1, 2, 3];
 type ExtractRelationRow<Rel> = Rel extends {
   table: infer R;
@@ -225,5 +330,5 @@ type ResolveResult<S extends readonly AnyTableDef[], T extends AnyTableDef, O> =
   with: infer W;
 } ? W : undefined>;
 //#endregion
-export { AnyTableDef, CacheConfig, ColumnDataType, ColumnMetadata, ConnectionConfig, DatabaseConfig, DatabaseDriver, DatabaseType, DeferredRefMeta, DeleteOptions, FileConnectionConfig, InferInsert, InferRow, InferUpdate, MigrationContext, MigrationDefinition, MySQLConnectionConfig, QueryOptions, ReferenceAction, RelationQueryMap, RelationsFor, Repository, ResolveResult, SQLiteConnectionConfig, TableDefinition, TableMetadata, UpdateOptions, WhereClause, WhereCondition };
+export { AnyTableDef, CacheConfig, ColumnDataType, ColumnMetadata, ConnectionConfig, DatabaseConfig, DatabaseDriver, DatabaseType, DeferredRefMeta, DeleteOptions, FileConnectionConfig, InferInsert, InferRow, InferSchemas, InferUpdate, MigrationContext, MigrationDefinition, MySQLConnectionConfig, QueryOptions, ReferenceAction, RelationQueryMap, RelationsFor, Repository, ResolveResult, SQLiteConnectionConfig, TableCacheConfig, TableDefinition, TableMetadata, UpdateOptions, WhereClause, WhereCondition };
 //# sourceMappingURL=types.d.mts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hedystia/db",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Next-gen TypeScript ORM for building type-safe database layers at lightspeed",
   "homepage": "https://docs.hedystia.com",
   "devDependencies": {