@hedystia/db 2.0.5 → 2.0.7

package/dist/schema/table.mjs

@@ -1,3 +1,4 @@
+import { __esmMin } from "../_virtual/_rolldown/runtime.mjs";
 //#region src/schema/table.ts
 /**
 * Define a database table with its columns
@@ -34,7 +35,9 @@ function table(name, columns, options) {
 		...columns
 	};
 }
+var init_table = __esmMin((() => {}));
 //#endregion
-export { table };
+init_table();
+export { init_table, table };
 
 //# sourceMappingURL=table.mjs.map

package/dist/schema/table.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"table.mjs","names":[],"sources":["../../src/schema/table.ts"],"sourcesContent":["import type { ColumnMetadata, DeferredRefMeta, TableCacheConfig, TableDefinition } from \"../types\";\nimport type { ColumnBuilder } from \"./column\";\n\ntype BindColumn<C, TableName extends string, ColName extends string> =\n  C extends ColumnBuilder<infer T, any, any, infer Ref>\n    ? ColumnBuilder<\n        T,\n        TableName,\n        ColName,\n        Ref extends DeferredRefMeta<any, infer ToTable, infer ToColumn, infer RelName>\n          ? DeferredRefMeta<ColName, ToTable, ToColumn, RelName>\n          : never\n      >\n    : never;\n\ntype BoundColumns<C extends Record<string, ColumnBuilder<any, any, any, any>>, N extends string> = {\n  [K in keyof C]: BindColumn<C[K], N, Extract<K, string>>;\n};\n\ntype ExtractDeferredRefs<C extends Record<string, ColumnBuilder<any, any, any, any>>> = {\n  [K in keyof C]: C[K] extends ColumnBuilder<any, any, any, infer Ref> ? Ref : never;\n}[keyof C];\n\n/**\n * Define a database table with its columns\n * @param {string} name - The table name\n * @param {Record<string, ColumnBuilder<any>>} columns - Column definitions\n * @returns {TableDefinition<T, C>} The table definition object with column accessors\n */\nexport function table<\n  N extends string,\n  C extends Record<string, ColumnBuilder<any, any, any, any>>,\n>(\n  name: N,\n  columns: C,\n  options?: { cache?: TableCacheConfig },\n): TableDefinition<\n  { [K in keyof C]: C[K][\"__type\"] },\n  BoundColumns<C, N>,\n  N,\n  ExtractDeferredRefs<BoundColumns<C, N>>\n> {\n  const columnsArray: ColumnMetadata[] = [];\n  const deferredRefs: TableDefinition[\"__deferredRefs\"] = [];\n  const columnMap: Record<string, string> = {};\n\n  for (const [key, builder] of Object.entries(columns)) {\n    const meta = builder.__build(key);\n    columnsArray.push(meta);\n    columnMap[key] = meta.name;\n\n    const ref = builder.__getDeferredRef();\n    if (ref) {\n      deferredRefs.push({\n        columnName: key,\n        resolve: ref.resolve,\n        onDelete: ref.onDelete,\n        onUpdate: ref.onUpdate,\n        relationName: ref.relationName,\n      });\n    }\n\n    (builder as any).__tableName = name;\n    (builder as any).__columnName = key;\n  }\n\n  const def = {\n    __table: true,\n    __name: name,\n    __columns: columnsArray,\n    __columnMap: columnMap,\n    __cache: options?.cache,\n    __deferredRefs: deferredRefs,\n    ...columns,\n  };\n\n  return def as any;\n}\n"],"mappings":";;;;;;;AA6BA,SAAgB,MAId,MACA,SACA,SAMA;CACA,MAAM,eAAiC,EAAE;CACzC,MAAM,eAAkD,EAAE;CAC1D,MAAM,YAAoC,EAAE;AAE5C,MAAK,MAAM,CAAC,KAAK,YAAY,OAAO,QAAQ,QAAQ,EAAE;EACpD,MAAM,OAAO,QAAQ,QAAQ,IAAI;AACjC,eAAa,KAAK,KAAK;AACvB,YAAU,OAAO,KAAK;EAEtB,MAAM,MAAM,QAAQ,kBAAkB;AACtC,MAAI,IACF,cAAa,KAAK;GAChB,YAAY;GACZ,SAAS,IAAI;GACb,UAAU,IAAI;GACd,UAAU,IAAI;GACd,cAAc,IAAI;GACnB,CAAC;AAGH,UAAgB,cAAc;AAC9B,UAAgB,eAAe;;AAalC,QAVY;EACV,SAAS;EACT,QAAQ;EACR,WAAW;EACX,aAAa;EACb,SAAS,SAAS;EAClB,gBAAgB;EAChB,GAAG;EACJ"}
+{"version":3,"file":"table.mjs","names":[],"sources":["../../src/schema/table.ts"],"sourcesContent":["import type { ColumnMetadata, DeferredRefMeta, TableCacheConfig, TableDefinition } from \"../types\";\nimport type { ColumnBuilder } from \"./column\";\n\ntype BindColumn<C, TableName extends string, ColName extends string> =\n  C extends ColumnBuilder<infer T, any, any, infer Ref>\n    ? ColumnBuilder<\n        T,\n        TableName,\n        ColName,\n        Ref extends DeferredRefMeta<any, infer ToTable, infer ToColumn, infer RelName>\n          ? DeferredRefMeta<ColName, ToTable, ToColumn, RelName>\n          : never\n      >\n    : never;\n\ntype BoundColumns<C extends Record<string, ColumnBuilder<any, any, any, any>>, N extends string> = {\n  [K in keyof C]: BindColumn<C[K], N, Extract<K, string>>;\n};\n\ntype ExtractDeferredRefs<C extends Record<string, ColumnBuilder<any, any, any, any>>> = {\n  [K in keyof C]: C[K] extends ColumnBuilder<any, any, any, infer Ref> ? Ref : never;\n}[keyof C];\n\n/**\n * Define a database table with its columns\n * @param {string} name - The table name\n * @param {Record<string, ColumnBuilder<any>>} columns - Column definitions\n * @returns {TableDefinition<T, C>} The table definition object with column accessors\n */\nexport function table<\n  N extends string,\n  C extends Record<string, ColumnBuilder<any, any, any, any>>,\n>(\n  name: N,\n  columns: C,\n  options?: { cache?: TableCacheConfig },\n): TableDefinition<\n  { [K in keyof C]: C[K][\"__type\"] },\n  BoundColumns<C, N>,\n  N,\n  ExtractDeferredRefs<BoundColumns<C, N>>\n> {\n  const columnsArray: ColumnMetadata[] = [];\n  const deferredRefs: TableDefinition[\"__deferredRefs\"] = [];\n  const columnMap: Record<string, string> = {};\n\n  for (const [key, builder] of Object.entries(columns)) {\n    const meta = builder.__build(key);\n    columnsArray.push(meta);\n    columnMap[key] = meta.name;\n\n    const ref = builder.__getDeferredRef();\n    if (ref) {\n      deferredRefs.push({\n        columnName: key,\n        resolve: ref.resolve,\n        onDelete: ref.onDelete,\n        onUpdate: ref.onUpdate,\n        relationName: ref.relationName,\n      });\n    }\n\n    (builder as any).__tableName = name;\n    (builder as any).__columnName = key;\n  }\n\n  const def = {\n    __table: true,\n    __name: name,\n    __columns: columnsArray,\n    __columnMap: columnMap,\n    __cache: options?.cache,\n    __deferredRefs: deferredRefs,\n    ...columns,\n  };\n\n  return def as any;\n}\n"],"mappings":";;;;;;;;AA6BA,SAAgB,MAId,MACA,SACA,SAMA;CACA,MAAM,eAAiC,EAAE;CACzC,MAAM,eAAkD,EAAE;CAC1D,MAAM,YAAoC,EAAE;AAE5C,MAAK,MAAM,CAAC,KAAK,YAAY,OAAO,QAAQ,QAAQ,EAAE;EACpD,MAAM,OAAO,QAAQ,QAAQ,IAAI;AACjC,eAAa,KAAK,KAAK;AACvB,YAAU,OAAO,KAAK;EAEtB,MAAM,MAAM,QAAQ,kBAAkB;AACtC,MAAI,IACF,cAAa,KAAK;GAChB,YAAY;GACZ,SAAS,IAAI;GACb,UAAU,IAAI;GACd,UAAU,IAAI;GACd,cAAc,IAAI;GACnB,CAAC;AAGH,UAAgB,cAAc;AAC9B,UAAgB,eAAe;;AAalC,QAVY;EACV,SAAS;EACT,QAAQ;EACR,WAAW;EACX,aAAa;EACb,SAAS,SAAS;EAClB,gBAAgB;EAChB,GAAG;EACJ"}

package/dist/sync/synchronizer.mjs

@@ -1,5 +1,6 @@
-import { SyncError } from "../errors.mjs";
+import { SyncError, init_errors } from "../errors.mjs";
 //#region src/sync/synchronizer.ts
+init_errors();
 /**
 * Schema synchronizer that compares the database state with the schema registry
 * and applies non-destructive changes

package/dist/sync/synchronizer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"synchronizer.mjs","names":[],"sources":["../../src/sync/synchronizer.ts"],"sourcesContent":["import { SyncError } from \"../errors\";\nimport type { SchemaRegistry } from \"../schema\";\nimport type { DatabaseDriver, TableMetadata } from \"../types\";\n\n/**\n * Schema synchronizer that compares the database state with the schema registry\n * and applies non-destructive changes\n */\nexport class Synchronizer {\n  private driver: DatabaseDriver;\n  private registry: SchemaRegistry;\n\n  constructor(driver: DatabaseDriver, registry: SchemaRegistry) {\n    this.driver = driver;\n    this.registry = registry;\n  }\n\n  /**\n   * Synchronize database schema with registry definitions\n   * @param {boolean} [force=false] - Allow destructive operations (drop columns)\n   */\n  async sync(force = false): Promise<void> {\n    const tables = this.registry.getAllTables();\n\n    for (const [, tableMeta] of tables) {\n      await this.syncTable(tableMeta, force);\n    }\n  }\n\n  private async syncTable(meta: TableMetadata, force: boolean): Promise<void> {\n    const exists = await this.driver.tableExists(meta.name);\n    if (!exists) {\n      await this.driver.createTable(meta);\n      return;\n    }\n\n    const existingCols = await this.driver.getTableColumns(meta.name);\n    const existingNames = new Set(existingCols.map((c) => c.name));\n    const schemaNames = new Set(meta.columns.map((c) => c.name));\n\n    for (const colMeta of meta.columns) {\n      if (!existingNames.has(colMeta.name)) {\n        await this.driver.addColumn(meta.name, colMeta);\n      }\n    }\n\n    if (force) {\n      for (const existingName of existingNames) {\n        if (!schemaNames.has(existingName)) {\n          try {\n            await this.driver.dropColumn(meta.name, existingName);\n          } catch (err: any) {\n            throw new SyncError(`Failed to drop column ${existingName}: ${err.message}`);\n          }\n        }\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;AAQA,IAAa,eAAb,MAA0B;CACxB;CACA;CAEA,YAAY,QAAwB,UAA0B;AAC5D,OAAK,SAAS;AACd,OAAK,WAAW;;;;;;CAOlB,MAAM,KAAK,QAAQ,OAAsB;EACvC,MAAM,SAAS,KAAK,SAAS,cAAc;AAE3C,OAAK,MAAM,GAAG,cAAc,OAC1B,OAAM,KAAK,UAAU,WAAW,MAAM;;CAI1C,MAAc,UAAU,MAAqB,OAA+B;AAE1E,MAAI,CADW,MAAM,KAAK,OAAO,YAAY,KAAK,KAAK,EAC1C;AACX,SAAM,KAAK,OAAO,YAAY,KAAK;AACnC;;EAGF,MAAM,eAAe,MAAM,KAAK,OAAO,gBAAgB,KAAK,KAAK;EACjE,MAAM,gBAAgB,IAAI,IAAI,aAAa,KAAK,MAAM,EAAE,KAAK,CAAC;EAC9D,MAAM,cAAc,IAAI,IAAI,KAAK,QAAQ,KAAK,MAAM,EAAE,KAAK,CAAC;AAE5D,OAAK,MAAM,WAAW,KAAK,QACzB,KAAI,CAAC,cAAc,IAAI,QAAQ,KAAK,CAClC,OAAM,KAAK,OAAO,UAAU,KAAK,MAAM,QAAQ;AAInD,MAAI;QACG,MAAM,gBAAgB,cACzB,KAAI,CAAC,YAAY,IAAI,aAAa,CAChC,KAAI;AACF,UAAM,KAAK,OAAO,WAAW,KAAK,MAAM,aAAa;YAC9C,KAAU;AACjB,UAAM,IAAI,UAAU,yBAAyB,aAAa,IAAI,IAAI,UAAU"}
+{"version":3,"file":"synchronizer.mjs","names":[],"sources":["../../src/sync/synchronizer.ts"],"sourcesContent":["import { SyncError } from \"../errors\";\nimport type { SchemaRegistry } from \"../schema\";\nimport type { DatabaseDriver, TableMetadata } from \"../types\";\n\n/**\n * Schema synchronizer that compares the database state with the schema registry\n * and applies non-destructive changes\n */\nexport class Synchronizer {\n  private driver: DatabaseDriver;\n  private registry: SchemaRegistry;\n\n  constructor(driver: DatabaseDriver, registry: SchemaRegistry) {\n    this.driver = driver;\n    this.registry = registry;\n  }\n\n  /**\n   * Synchronize database schema with registry definitions\n   * @param {boolean} [force=false] - Allow destructive operations (drop columns)\n   */\n  async sync(force = false): Promise<void> {\n    const tables = this.registry.getAllTables();\n\n    for (const [, tableMeta] of tables) {\n      await this.syncTable(tableMeta, force);\n    }\n  }\n\n  private async syncTable(meta: TableMetadata, force: boolean): Promise<void> {\n    const exists = await this.driver.tableExists(meta.name);\n    if (!exists) {\n      await this.driver.createTable(meta);\n      return;\n    }\n\n    const existingCols = await this.driver.getTableColumns(meta.name);\n    const existingNames = new Set(existingCols.map((c) => c.name));\n    const schemaNames = new Set(meta.columns.map((c) => c.name));\n\n    for (const colMeta of meta.columns) {\n      if (!existingNames.has(colMeta.name)) {\n        await this.driver.addColumn(meta.name, colMeta);\n      }\n    }\n\n    if (force) {\n      for (const existingName of existingNames) {\n        if (!schemaNames.has(existingName)) {\n          try {\n            await this.driver.dropColumn(meta.name, existingName);\n          } catch (err: any) {\n            throw new SyncError(`Failed to drop column ${existingName}: ${err.message}`);\n          }\n        }\n      }\n    }\n  }\n}\n"],"mappings":";;aAAsC;;;;;AAQtC,IAAa,eAAb,MAA0B;CACxB;CACA;CAEA,YAAY,QAAwB,UAA0B;AAC5D,OAAK,SAAS;AACd,OAAK,WAAW;;;;;;CAOlB,MAAM,KAAK,QAAQ,OAAsB;EACvC,MAAM,SAAS,KAAK,SAAS,cAAc;AAE3C,OAAK,MAAM,GAAG,cAAc,OAC1B,OAAM,KAAK,UAAU,WAAW,MAAM;;CAI1C,MAAc,UAAU,MAAqB,OAA+B;AAE1E,MAAI,CADW,MAAM,KAAK,OAAO,YAAY,KAAK,KAAK,EAC1C;AACX,SAAM,KAAK,OAAO,YAAY,KAAK;AACnC;;EAGF,MAAM,eAAe,MAAM,KAAK,OAAO,gBAAgB,KAAK,KAAK;EACjE,MAAM,gBAAgB,IAAI,IAAI,aAAa,KAAK,MAAM,EAAE,KAAK,CAAC;EAC9D,MAAM,cAAc,IAAI,IAAI,KAAK,QAAQ,KAAK,MAAM,EAAE,KAAK,CAAC;AAE5D,OAAK,MAAM,WAAW,KAAK,QACzB,KAAI,CAAC,cAAc,IAAI,QAAQ,KAAK,CAClC,OAAM,KAAK,OAAO,UAAU,KAAK,MAAM,QAAQ;AAInD,MAAI;QACG,MAAM,gBAAgB,cACzB,KAAI,CAAC,YAAY,IAAI,aAAa,CAChC,KAAI;AACF,UAAM,KAAK,OAAO,WAAW,KAAK,MAAM,aAAa;YAC9C,KAAU;AACjB,UAAM,IAAI,UAAU,yBAAyB,aAAa,IAAI,IAAI,UAAU"}

package/dist/types.d.cts

@@ -101,26 +101,76 @@ type InferInsert<T> = T extends TableDefinition<infer R, any, any> ? { [K in key
 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 */
+/**
+ * Condition operators for a single column in a WHERE clause.
+ *
+ * @example
+ * ```ts
+ * // Exact match
+ * { age: { eq: 25 } }
+ * // Range query
+ * { age: { gte: 18, lte: 65 } }
+ * // Pattern matching
+ * { name: { like: "%alice%" } }
+ * // Set membership
+ * { status: { in: ["active", "pending"] } }
+ * ```
+ */
 interface WhereCondition {
+  /** Equal to — matches rows where the column value equals the given value */
   eq?: unknown;
+  /** Not equal to — matches rows where the column value differs from the given value */
   neq?: unknown;
+  /** Greater than — matches rows where the column value is strictly greater */
   gt?: unknown;
+  /** Greater than or equal to — matches rows where the column value is greater or equal */
   gte?: unknown;
+  /** Less than — matches rows where the column value is strictly less */
   lt?: unknown;
+  /** Less than or equal to — matches rows where the column value is less or equal */
   lte?: unknown;
+  /** SQL LIKE — matches rows where the column value matches the pattern (use `%` as wildcard) */
   like?: string;
+  /** SQL NOT LIKE — matches rows where the column value does not match the pattern */
   notLike?: string;
+  /** IN — matches rows where the column value is one of the given values */
   in?: unknown[];
+  /** NOT IN — matches rows where the column value is not one of the given values */
   notIn?: unknown[];
+  /** IS NULL / IS NOT NULL — when `true`, matches rows where the column is NULL; when `false`, matches non-NULL */
   isNull?: boolean;
+  /** BETWEEN — matches rows where the column value falls within the inclusive range `[min, max]` */
   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>[];
-};
+/** Flatten an intersection into a single object type for better autocomplete */
+type Flat<T> = { [K in keyof T]: T[K] } & {};
+/** Column-level filter conditions for a WHERE clause */
+type WhereFields<T> = Flat<{ [K in keyof T]?: T[K] | WhereCondition }>;
+/**
+ * Type-safe WHERE clause supporting equality, operators, and logical combinators (OR/AND).
+ *
+ * @example
+ * ```ts
+ * // Simple equality
+ * { where: { name: "Alice" } }
+ *
+ * // Using operators
+ * { where: { age: { gte: 18 } } }
+ *
+ * // OR — matches rows satisfying at least one condition
+ * { where: { OR: [{ name: "Alice" }, { name: "Bob" }] } }
+ *
+ * // AND — matches rows satisfying all conditions
+ * { where: { AND: [{ age: { gte: 18 } }, { active: true }] } }
+ *
+ * // Combined AND + OR
+ * { where: { AND: [{ age: { gte: 18 } }], OR: [{ name: "Alice" }, { name: "Bob" }] } }
+ * ```
+ */
+type WhereClause<T = Record<string, any>> = Flat<{ [K in keyof T]?: T[K] | WhereCondition } & {
+  /** Logical OR — matches rows satisfying **at least one** of the given conditions */OR?: WhereFields<T>[]; /** Logical AND — matches rows satisfying **all** of the given conditions */
+  AND?: WhereFields<T>[];
+}>;
 /** Options for querying rows — filtering, sorting, pagination, and relation loading */
 interface QueryOptions<T = Record<string, any>, Rel extends Record<string, any> = {}> {
   /** Filter conditions */
@@ -271,20 +321,31 @@ interface DatabaseDriver {
 }
 /** Generic repository interface providing CRUD operations for a table */
 interface Repository<T extends Record<string, any>> {
+  /** Find all rows matching the given options */
   find(options?: QueryOptions<T>): Promise<T[]>;
+  /** Find all rows matching the given options (alias for {@link find}) */
   findMany(options?: QueryOptions<T>): Promise<T[]>;
+  /** Find the first row matching the given options, or `null` if none found */
   findFirst(options?: QueryOptions<T>): Promise<T | null>;
+  /** Insert one or more rows into the table */
   insert(data: Partial<T> | Partial<T>[]): Promise<T>;
+  /** Insert multiple rows into the table */
   insertMany(data: Partial<T>[]): Promise<T[]>;
+  /** Update rows matching the where clause */
   update(options: UpdateOptions<T>): Promise<T[]>;
+  /** Delete rows matching the where clause */
   delete(options: DeleteOptions<T>): Promise<number>;
+  /** Count rows matching the where clause */
   count(options?: Pick<QueryOptions<T>, "where">): Promise<number>;
+  /** Check whether at least one row matches the where clause */
   exists(options: Pick<QueryOptions<T>, "where">): Promise<boolean>;
+  /** Insert a row if it doesn't exist, or update it if it does */
   upsert(options: {
     where: WhereClause<T>;
     create: Partial<T>;
     update: Partial<T>;
   }): Promise<T>;
+  /** Remove all rows from the table */
   truncate(): Promise<void>;
 }
 type AnyTableDef = TableDefinition<any, any, any, any>;

package/dist/types.d.mts

@@ -101,26 +101,76 @@ type InferInsert<T> = T extends TableDefinition<infer R, any, any> ? { [K in key
 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 */
+/**
+ * Condition operators for a single column in a WHERE clause.
+ *
+ * @example
+ * ```ts
+ * // Exact match
+ * { age: { eq: 25 } }
+ * // Range query
+ * { age: { gte: 18, lte: 65 } }
+ * // Pattern matching
+ * { name: { like: "%alice%" } }
+ * // Set membership
+ * { status: { in: ["active", "pending"] } }
+ * ```
+ */
 interface WhereCondition {
+  /** Equal to — matches rows where the column value equals the given value */
   eq?: unknown;
+  /** Not equal to — matches rows where the column value differs from the given value */
   neq?: unknown;
+  /** Greater than — matches rows where the column value is strictly greater */
   gt?: unknown;
+  /** Greater than or equal to — matches rows where the column value is greater or equal */
   gte?: unknown;
+  /** Less than — matches rows where the column value is strictly less */
   lt?: unknown;
+  /** Less than or equal to — matches rows where the column value is less or equal */
   lte?: unknown;
+  /** SQL LIKE — matches rows where the column value matches the pattern (use `%` as wildcard) */
   like?: string;
+  /** SQL NOT LIKE — matches rows where the column value does not match the pattern */
   notLike?: string;
+  /** IN — matches rows where the column value is one of the given values */
   in?: unknown[];
+  /** NOT IN — matches rows where the column value is not one of the given values */
   notIn?: unknown[];
+  /** IS NULL / IS NOT NULL — when `true`, matches rows where the column is NULL; when `false`, matches non-NULL */
   isNull?: boolean;
+  /** BETWEEN — matches rows where the column value falls within the inclusive range `[min, max]` */
   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>[];
-};
+/** Flatten an intersection into a single object type for better autocomplete */
+type Flat<T> = { [K in keyof T]: T[K] } & {};
+/** Column-level filter conditions for a WHERE clause */
+type WhereFields<T> = Flat<{ [K in keyof T]?: T[K] | WhereCondition }>;
+/**
+ * Type-safe WHERE clause supporting equality, operators, and logical combinators (OR/AND).
+ *
+ * @example
+ * ```ts
+ * // Simple equality
+ * { where: { name: "Alice" } }
+ *
+ * // Using operators
+ * { where: { age: { gte: 18 } } }
+ *
+ * // OR — matches rows satisfying at least one condition
+ * { where: { OR: [{ name: "Alice" }, { name: "Bob" }] } }
+ *
+ * // AND — matches rows satisfying all conditions
+ * { where: { AND: [{ age: { gte: 18 } }, { active: true }] } }
+ *
+ * // Combined AND + OR
+ * { where: { AND: [{ age: { gte: 18 } }], OR: [{ name: "Alice" }, { name: "Bob" }] } }
+ * ```
+ */
+type WhereClause<T = Record<string, any>> = Flat<{ [K in keyof T]?: T[K] | WhereCondition } & {
+  /** Logical OR — matches rows satisfying **at least one** of the given conditions */OR?: WhereFields<T>[]; /** Logical AND — matches rows satisfying **all** of the given conditions */
+  AND?: WhereFields<T>[];
+}>;
 /** Options for querying rows — filtering, sorting, pagination, and relation loading */
 interface QueryOptions<T = Record<string, any>, Rel extends Record<string, any> = {}> {
   /** Filter conditions */
@@ -271,20 +321,31 @@ interface DatabaseDriver {
 }
 /** Generic repository interface providing CRUD operations for a table */
 interface Repository<T extends Record<string, any>> {
+  /** Find all rows matching the given options */
   find(options?: QueryOptions<T>): Promise<T[]>;
+  /** Find all rows matching the given options (alias for {@link find}) */
   findMany(options?: QueryOptions<T>): Promise<T[]>;
+  /** Find the first row matching the given options, or `null` if none found */
   findFirst(options?: QueryOptions<T>): Promise<T | null>;
+  /** Insert one or more rows into the table */
   insert(data: Partial<T> | Partial<T>[]): Promise<T>;
+  /** Insert multiple rows into the table */
   insertMany(data: Partial<T>[]): Promise<T[]>;
+  /** Update rows matching the where clause */
   update(options: UpdateOptions<T>): Promise<T[]>;
+  /** Delete rows matching the where clause */
   delete(options: DeleteOptions<T>): Promise<number>;
+  /** Count rows matching the where clause */
   count(options?: Pick<QueryOptions<T>, "where">): Promise<number>;
+  /** Check whether at least one row matches the where clause */
   exists(options: Pick<QueryOptions<T>, "where">): Promise<boolean>;
+  /** Insert a row if it doesn't exist, or update it if it does */
   upsert(options: {
     where: WhereClause<T>;
     create: Partial<T>;
     update: Partial<T>;
   }): Promise<T>;
+  /** Remove all rows from the table */
   truncate(): Promise<void>;
 }
 type AnyTableDef = TableDefinition<any, any, any, any>;

package/package.json

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