@hedystia/db 2.0.2 → 2.0.4

package/dist/schema/columns/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/schema/columns/index.ts"],"sourcesContent":["import { ColumnBuilder } from \"../column\";\n\n/**\n * Create an INTEGER column\n * @returns {ColumnBuilder<number>} Column builder for integer type\n */\nexport const integer = (): ColumnBuilder<number> => new ColumnBuilder<number>(\"integer\");\n\n/**\n * Create a BIGINT column\n * @returns {ColumnBuilder<number>} Column builder for bigint type\n */\nexport const bigint = (): ColumnBuilder<number> => new ColumnBuilder<number>(\"bigint\");\n\n/**\n * Create a VARCHAR column with specified length\n * @param {number} [length=255] - Maximum character length\n * @returns {ColumnBuilder<string>} Column builder for varchar type\n */\nexport const varchar = (length = 255): ColumnBuilder<string> =>\n  new ColumnBuilder<string>(\"varchar\", length);\n\n/**\n * Create a CHAR column with specified length\n * @param {number} [length=1] - Fixed character length\n * @returns {ColumnBuilder<string>} Column builder for char type\n */\nexport const char = (length = 1): ColumnBuilder<string> =>\n  new ColumnBuilder<string>(\"char\", length);\n\n/**\n * Create a TEXT column\n * @returns {ColumnBuilder<string>} Column builder for text type\n */\nexport const text = (): ColumnBuilder<string> => new ColumnBuilder<string>(\"text\");\n\n/**\n * Create a BOOLEAN column\n * @returns {ColumnBuilder<boolean>} Column builder for boolean type\n */\nexport const boolean = (): ColumnBuilder<boolean> => new ColumnBuilder<boolean>(\"boolean\");\n\n/**\n * Create a JSON column\n * @returns {ColumnBuilder<unknown>} Column builder for json type\n */\nexport const json = (): ColumnBuilder<unknown> => new ColumnBuilder<unknown>(\"json\");\n\n/**\n * Create a DATETIME column\n * @returns {ColumnBuilder<Date>} Column builder for datetime type\n */\nexport const datetime = (): ColumnBuilder<Date> => new ColumnBuilder<Date>(\"datetime\");\n\n/**\n * Create a TIMESTAMP column\n * @returns {ColumnBuilder<Date>} Column builder for timestamp type\n */\nexport const timestamp = (): ColumnBuilder<Date> => new ColumnBuilder<Date>(\"timestamp\");\n\n/**\n * Create a DECIMAL column with precision and scale\n * @param {number} [precision=10] - Total number of digits\n * @param {number} [scale=2] - Number of decimal digits\n * @returns {ColumnBuilder<number>} Column builder for decimal type\n */\nexport const decimal = (precision = 10, scale = 2): ColumnBuilder<number> =>\n  new ColumnBuilder<number>(\"decimal\", undefined, precision, scale);\n\n/**\n * Create a FLOAT column\n * @returns {ColumnBuilder<number>} Column builder for float type\n */\nexport const float = (): ColumnBuilder<number> => new ColumnBuilder<number>(\"float\");\n\n/**\n * Create a BLOB column\n * @returns {ColumnBuilder<Buffer>} Column builder for blob type\n */\nexport const blob = (): ColumnBuilder<Buffer> => new ColumnBuilder<Buffer>(\"blob\");\n\n/**\n * Starter class for creating columns with a pre-set database column name\n * @example\n * // Start with name, then pick column type\n * guildId: name(\"guild_id\").varchar(255)\n */\nexport class NamedColumnStarter {\n  private _alias: string;\n\n  constructor(alias: string) {\n    this._alias = alias;\n  }\n\n  /** Create an INTEGER column with this database column name */\n  integer(): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"integer\").name(this._alias);\n  }\n\n  /** Create a BIGINT column with this database column name */\n  bigint(): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"bigint\").name(this._alias);\n  }\n\n  /** Create a VARCHAR column with this database column name\n   * @param {number} [length=255] - Maximum character length\n   */\n  varchar(length = 255): ColumnBuilder<string> {\n    return new ColumnBuilder<string>(\"varchar\", length).name(this._alias);\n  }\n\n  /** Create a CHAR column with this database column name\n   * @param {number} [length=1] - Fixed character length\n   */\n  char(length = 1): ColumnBuilder<string> {\n    return new ColumnBuilder<string>(\"char\", length).name(this._alias);\n  }\n\n  /** Create a TEXT column with this database column name */\n  text(): ColumnBuilder<string> {\n    return new ColumnBuilder<string>(\"text\").name(this._alias);\n  }\n\n  /** Create a BOOLEAN column with this database column name */\n  boolean(): ColumnBuilder<boolean> {\n    return new ColumnBuilder<boolean>(\"boolean\").name(this._alias);\n  }\n\n  /** Create a JSON column with this database column name */\n  json(): ColumnBuilder<unknown> {\n    return new ColumnBuilder<unknown>(\"json\").name(this._alias);\n  }\n\n  /** Create a DATETIME column with this database column name */\n  datetime(): ColumnBuilder<Date> {\n    return new ColumnBuilder<Date>(\"datetime\").name(this._alias);\n  }\n\n  /** Create a TIMESTAMP column with this database column name */\n  timestamp(): ColumnBuilder<Date> {\n    return new ColumnBuilder<Date>(\"timestamp\").name(this._alias);\n  }\n\n  /** Create a DECIMAL column with this database column name\n   * @param {number} [precision=10] - Total number of digits\n   * @param {number} [scale=2] - Number of decimal digits\n   */\n  decimal(precision = 10, scale = 2): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"decimal\", undefined, precision, scale).name(this._alias);\n  }\n\n  /** Create a FLOAT column with this database column name */\n  float(): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"float\").name(this._alias);\n  }\n\n  /** Create a BLOB column with this database column name */\n  blob(): ColumnBuilder<Buffer> {\n    return new ColumnBuilder<Buffer>(\"blob\").name(this._alias);\n  }\n}\n\n/**\n * Create a column with a custom database column name, then pick the column type\n * @param {string} alias - The column name to use in the database\n * @returns {NamedColumnStarter} A starter object to pick the column type\n * @example\n * guildId: name(\"guild_id\").varchar(255).notNull()\n */\nexport const name = (alias: string): NamedColumnStarter => new NamedColumnStarter(alias);\n\n/**\n * Column type helpers object for schema definitions\n * @returns {typeof d} Column type helpers\n */\nexport const d = {\n  integer,\n  bigint,\n  varchar,\n  char,\n  text,\n  boolean,\n  json,\n  datetime,\n  timestamp,\n  decimal,\n  float,\n  blob,\n  name,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAMA,MAAa,gBAAuC,IAAI,cAAsB,UAAU;;;;;AAMxF,MAAa,eAAsC,IAAI,cAAsB,SAAS;;;;;;AAOtF,MAAa,WAAW,SAAS,QAC/B,IAAI,cAAsB,WAAW,OAAO;;;;;;AAO9C,MAAa,QAAQ,SAAS,MAC5B,IAAI,cAAsB,QAAQ,OAAO;;;;;AAM3C,MAAa,aAAoC,IAAI,cAAsB,OAAO;;;;;AAMlF,MAAa,gBAAwC,IAAI,cAAuB,UAAU;;;;;AAM1F,MAAa,aAAqC,IAAI,cAAuB,OAAO;;;;;AAMpF,MAAa,iBAAsC,IAAI,cAAoB,WAAW;;;;;AAMtF,MAAa,kBAAuC,IAAI,cAAoB,YAAY;;;;;;;AAQxF,MAAa,WAAW,YAAY,IAAI,QAAQ,MAC9C,IAAI,cAAsB,WAAW,KAAA,GAAW,WAAW,MAAM;;;;;AAMnE,MAAa,cAAqC,IAAI,cAAsB,QAAQ;;;;;AAMpF,MAAa,aAAoC,IAAI,cAAsB,OAAO;;;;;;;AAQlF,IAAa,qBAAb,MAAgC;CAC9B;CAEA,YAAY,OAAe;AACzB,OAAK,SAAS;;;CAIhB,UAAiC;AAC/B,SAAO,IAAI,cAAsB,UAAU,CAAC,KAAK,KAAK,OAAO;;;CAI/D,SAAgC;AAC9B,SAAO,IAAI,cAAsB,SAAS,CAAC,KAAK,KAAK,OAAO;;;;;CAM9D,QAAQ,SAAS,KAA4B;AAC3C,SAAO,IAAI,cAAsB,WAAW,OAAO,CAAC,KAAK,KAAK,OAAO;;;;;CAMvE,KAAK,SAAS,GAA0B;AACtC,SAAO,IAAI,cAAsB,QAAQ,OAAO,CAAC,KAAK,KAAK,OAAO;;;CAIpE,OAA8B;AAC5B,SAAO,IAAI,cAAsB,OAAO,CAAC,KAAK,KAAK,OAAO;;;CAI5D,UAAkC;AAChC,SAAO,IAAI,cAAuB,UAAU,CAAC,KAAK,KAAK,OAAO;;;CAIhE,OAA+B;AAC7B,SAAO,IAAI,cAAuB,OAAO,CAAC,KAAK,KAAK,OAAO;;;CAI7D,WAAgC;AAC9B,SAAO,IAAI,cAAoB,WAAW,CAAC,KAAK,KAAK,OAAO;;;CAI9D,YAAiC;AAC/B,SAAO,IAAI,cAAoB,YAAY,CAAC,KAAK,KAAK,OAAO;;;;;;CAO/D,QAAQ,YAAY,IAAI,QAAQ,GAA0B;AACxD,SAAO,IAAI,cAAsB,WAAW,KAAA,GAAW,WAAW,MAAM,CAAC,KAAK,KAAK,OAAO;;;CAI5F,QAA+B;AAC7B,SAAO,IAAI,cAAsB,QAAQ,CAAC,KAAK,KAAK,OAAO;;;CAI7D,OAA8B;AAC5B,SAAO,IAAI,cAAsB,OAAO,CAAC,KAAK,KAAK,OAAO;;;;;;;;;;AAW9D,MAAa,QAAQ,UAAsC,IAAI,mBAAmB,MAAM;;;;;AAMxF,MAAa,IAAI;CACf;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/schema/columns/index.ts"],"sourcesContent":["import { ColumnBuilder } from \"../column\";\n\n/**\n * Create an INTEGER column\n * @returns {ColumnBuilder<number>} Column builder for integer type\n */\nexport const integer = (): ColumnBuilder<number> => new ColumnBuilder<number>(\"integer\");\n\n/**\n * Create a BIGINT column\n * @returns {ColumnBuilder<number>} Column builder for bigint type\n */\nexport const bigint = (): ColumnBuilder<number> => new ColumnBuilder<number>(\"bigint\");\n\n/**\n * Create a VARCHAR column with specified length\n * @param {number} [length=255] - Maximum character length\n * @returns {ColumnBuilder<string>} Column builder for varchar type\n */\nexport const varchar = (length = 255): ColumnBuilder<string> =>\n  new ColumnBuilder<string>(\"varchar\", length);\n\n/**\n * Create a CHAR column with specified length\n * @param {number} [length=1] - Fixed character length\n * @returns {ColumnBuilder<string>} Column builder for char type\n */\nexport const char = (length = 1): ColumnBuilder<string> =>\n  new ColumnBuilder<string>(\"char\", length);\n\n/**\n * Create a TEXT column\n * @returns {ColumnBuilder<string>} Column builder for text type\n */\nexport const text = (): ColumnBuilder<string> => new ColumnBuilder<string>(\"text\");\n\n/**\n * Create a BOOLEAN column\n * @returns {ColumnBuilder<boolean>} Column builder for boolean type\n */\nexport const boolean = (): ColumnBuilder<boolean> => new ColumnBuilder<boolean>(\"boolean\");\n\n/**\n * Create a JSON column\n * @returns {ColumnBuilder<unknown>} Column builder for json type\n */\nexport const json = (): ColumnBuilder<unknown> => new ColumnBuilder<unknown>(\"json\");\n\n/**\n * Create an ARRAY column (stored as JSON)\n * @returns {ColumnBuilder<unknown[]>} Column builder for array type\n */\nexport const array = (): ColumnBuilder<unknown[]> => new ColumnBuilder<unknown[]>(\"array\");\n\n/**\n * Create a DATETIME column\n * @returns {ColumnBuilder<Date>} Column builder for datetime type\n */\nexport const datetime = (): ColumnBuilder<Date> => new ColumnBuilder<Date>(\"datetime\");\n\n/**\n * Create a TIMESTAMP column\n * @returns {ColumnBuilder<Date>} Column builder for timestamp type\n */\nexport const timestamp = (): ColumnBuilder<Date> => new ColumnBuilder<Date>(\"timestamp\");\n\n/**\n * Create a DECIMAL column with precision and scale\n * @param {number} [precision=10] - Total number of digits\n * @param {number} [scale=2] - Number of decimal digits\n * @returns {ColumnBuilder<number>} Column builder for decimal type\n */\nexport const decimal = (precision = 10, scale = 2): ColumnBuilder<number> =>\n  new ColumnBuilder<number>(\"decimal\", undefined, precision, scale);\n\n/**\n * Create a FLOAT column\n * @returns {ColumnBuilder<number>} Column builder for float type\n */\nexport const float = (): ColumnBuilder<number> => new ColumnBuilder<number>(\"float\");\n\n/**\n * Create a BLOB column\n * @returns {ColumnBuilder<Buffer>} Column builder for blob type\n */\nexport const blob = (): ColumnBuilder<Buffer> => new ColumnBuilder<Buffer>(\"blob\");\n\n/**\n * Starter class for creating columns with a pre-set database column name\n * @example\n * // Start with name, then pick column type\n * guildId: name(\"guild_id\").varchar(255)\n */\nexport class NamedColumnStarter {\n  private _alias: string;\n\n  constructor(alias: string) {\n    this._alias = alias;\n  }\n\n  /** Create an INTEGER column with this database column name */\n  integer(): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"integer\").name(this._alias);\n  }\n\n  /** Create a BIGINT column with this database column name */\n  bigint(): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"bigint\").name(this._alias);\n  }\n\n  /** Create a VARCHAR column with this database column name\n   * @param {number} [length=255] - Maximum character length\n   */\n  varchar(length = 255): ColumnBuilder<string> {\n    return new ColumnBuilder<string>(\"varchar\", length).name(this._alias);\n  }\n\n  /** Create a CHAR column with this database column name\n   * @param {number} [length=1] - Fixed character length\n   */\n  char(length = 1): ColumnBuilder<string> {\n    return new ColumnBuilder<string>(\"char\", length).name(this._alias);\n  }\n\n  /** Create a TEXT column with this database column name */\n  text(): ColumnBuilder<string> {\n    return new ColumnBuilder<string>(\"text\").name(this._alias);\n  }\n\n  /** Create a BOOLEAN column with this database column name */\n  boolean(): ColumnBuilder<boolean> {\n    return new ColumnBuilder<boolean>(\"boolean\").name(this._alias);\n  }\n\n  /** Create a JSON column with this database column name */\n  json(): ColumnBuilder<unknown> {\n    return new ColumnBuilder<unknown>(\"json\").name(this._alias);\n  }\n\n  /** Create an ARRAY column with this database column name */\n  array(): ColumnBuilder<unknown[]> {\n    return new ColumnBuilder<unknown[]>(\"array\").name(this._alias);\n  }\n\n  /** Create a DATETIME column with this database column name */\n  datetime(): ColumnBuilder<Date> {\n    return new ColumnBuilder<Date>(\"datetime\").name(this._alias);\n  }\n\n  /** Create a TIMESTAMP column with this database column name */\n  timestamp(): ColumnBuilder<Date> {\n    return new ColumnBuilder<Date>(\"timestamp\").name(this._alias);\n  }\n\n  /** Create a DECIMAL column with this database column name\n   * @param {number} [precision=10] - Total number of digits\n   * @param {number} [scale=2] - Number of decimal digits\n   */\n  decimal(precision = 10, scale = 2): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"decimal\", undefined, precision, scale).name(this._alias);\n  }\n\n  /** Create a FLOAT column with this database column name */\n  float(): ColumnBuilder<number> {\n    return new ColumnBuilder<number>(\"float\").name(this._alias);\n  }\n\n  /** Create a BLOB column with this database column name */\n  blob(): ColumnBuilder<Buffer> {\n    return new ColumnBuilder<Buffer>(\"blob\").name(this._alias);\n  }\n}\n\n/**\n * Create a column with a custom database column name, then pick the column type\n * @param {string} alias - The column name to use in the database\n * @returns {NamedColumnStarter} A starter object to pick the column type\n * @example\n * guildId: name(\"guild_id\").varchar(255).notNull()\n */\nexport const name = (alias: string): NamedColumnStarter => new NamedColumnStarter(alias);\n\n/**\n * Column type helpers object for schema definitions\n * @returns {typeof d} Column type helpers\n */\nexport const d = {\n  integer,\n  bigint,\n  varchar,\n  char,\n  text,\n  boolean,\n  json,\n  array,\n  datetime,\n  timestamp,\n  decimal,\n  float,\n  blob,\n  name,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAMA,MAAa,gBAAuC,IAAI,cAAsB,UAAU;;;;;AAMxF,MAAa,eAAsC,IAAI,cAAsB,SAAS;;;;;;AAOtF,MAAa,WAAW,SAAS,QAC/B,IAAI,cAAsB,WAAW,OAAO;;;;;;AAO9C,MAAa,QAAQ,SAAS,MAC5B,IAAI,cAAsB,QAAQ,OAAO;;;;;AAM3C,MAAa,aAAoC,IAAI,cAAsB,OAAO;;;;;AAMlF,MAAa,gBAAwC,IAAI,cAAuB,UAAU;;;;;AAM1F,MAAa,aAAqC,IAAI,cAAuB,OAAO;;;;;AAMpF,MAAa,cAAwC,IAAI,cAAyB,QAAQ;;;;;AAM1F,MAAa,iBAAsC,IAAI,cAAoB,WAAW;;;;;AAMtF,MAAa,kBAAuC,IAAI,cAAoB,YAAY;;;;;;;AAQxF,MAAa,WAAW,YAAY,IAAI,QAAQ,MAC9C,IAAI,cAAsB,WAAW,KAAA,GAAW,WAAW,MAAM;;;;;AAMnE,MAAa,cAAqC,IAAI,cAAsB,QAAQ;;;;;AAMpF,MAAa,aAAoC,IAAI,cAAsB,OAAO;;;;;;;AAQlF,IAAa,qBAAb,MAAgC;CAC9B;CAEA,YAAY,OAAe;AACzB,OAAK,SAAS;;;CAIhB,UAAiC;AAC/B,SAAO,IAAI,cAAsB,UAAU,CAAC,KAAK,KAAK,OAAO;;;CAI/D,SAAgC;AAC9B,SAAO,IAAI,cAAsB,SAAS,CAAC,KAAK,KAAK,OAAO;;;;;CAM9D,QAAQ,SAAS,KAA4B;AAC3C,SAAO,IAAI,cAAsB,WAAW,OAAO,CAAC,KAAK,KAAK,OAAO;;;;;CAMvE,KAAK,SAAS,GAA0B;AACtC,SAAO,IAAI,cAAsB,QAAQ,OAAO,CAAC,KAAK,KAAK,OAAO;;;CAIpE,OAA8B;AAC5B,SAAO,IAAI,cAAsB,OAAO,CAAC,KAAK,KAAK,OAAO;;;CAI5D,UAAkC;AAChC,SAAO,IAAI,cAAuB,UAAU,CAAC,KAAK,KAAK,OAAO;;;CAIhE,OAA+B;AAC7B,SAAO,IAAI,cAAuB,OAAO,CAAC,KAAK,KAAK,OAAO;;;CAI7D,QAAkC;AAChC,SAAO,IAAI,cAAyB,QAAQ,CAAC,KAAK,KAAK,OAAO;;;CAIhE,WAAgC;AAC9B,SAAO,IAAI,cAAoB,WAAW,CAAC,KAAK,KAAK,OAAO;;;CAI9D,YAAiC;AAC/B,SAAO,IAAI,cAAoB,YAAY,CAAC,KAAK,KAAK,OAAO;;;;;;CAO/D,QAAQ,YAAY,IAAI,QAAQ,GAA0B;AACxD,SAAO,IAAI,cAAsB,WAAW,KAAA,GAAW,WAAW,MAAM,CAAC,KAAK,KAAK,OAAO;;;CAI5F,QAA+B;AAC7B,SAAO,IAAI,cAAsB,QAAQ,CAAC,KAAK,KAAK,OAAO;;;CAI7D,OAA8B;AAC5B,SAAO,IAAI,cAAsB,OAAO,CAAC,KAAK,KAAK,OAAO;;;;;;;;;;AAW9D,MAAa,QAAQ,UAAsC,IAAI,mBAAmB,MAAM;;;;;AAMxF,MAAa,IAAI;CACf;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD"}

package/dist/schema/table.cjs

@@ -5,7 +5,7 @@
 * @param {Record<string, ColumnBuilder<any>>} columns - Column definitions
 * @returns {TableDefinition<T, C>} The table definition object with column accessors
 */
-function table(name, columns) {
+function table(name, columns, options) {
 	const columnsArray = [];
 	const deferredRefs = [];
 	const columnMap = {};
@@ -29,6 +29,7 @@ function table(name, columns) {
 		__name: name,
 		__columns: columnsArray,
 		__columnMap: columnMap,
+		__cache: options?.cache,
 		__deferredRefs: deferredRefs,
 		...columns
 	};

package/dist/schema/table.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"table.cjs","names":[],"sources":["../../src/schema/table.ts"],"sourcesContent":["import type { ColumnMetadata, DeferredRefMeta, 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): 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    __deferredRefs: deferredRefs,\n    ...columns,\n  };\n\n  return def as any;\n}\n"],"mappings":";;;;;;;AA6BA,SAAgB,MAId,MACA,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;;AAYlC,QATY;EACV,SAAS;EACT,QAAQ;EACR,WAAW;EACX,aAAa;EACb,gBAAgB;EAChB,GAAG;EACJ"}
+{"version":3,"file":"table.cjs","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/schema/table.d.cts

@@ -1,4 +1,4 @@
-import { DeferredRefMeta, TableDefinition } from "../types.cjs";
+import { DeferredRefMeta, TableCacheConfig, TableDefinition } from "../types.cjs";
 import { ColumnBuilder } from "./column.cjs";
 
 //#region src/schema/table.d.ts
@@ -11,7 +11,9 @@ type ExtractDeferredRefs<C extends Record<string, ColumnBuilder<any, any, any, a
  * @param {Record<string, ColumnBuilder<any>>} columns - Column definitions
  * @returns {TableDefinition<T, C>} The table definition object with column accessors
  */
-declare function table<N extends string, C extends Record<string, ColumnBuilder<any, any, any, any>>>(name: N, columns: C): TableDefinition<{ [K in keyof C]: C[K]["__type"] }, BoundColumns<C, N>, N, ExtractDeferredRefs<BoundColumns<C, N>>>;
+declare function table<N extends string, C extends Record<string, ColumnBuilder<any, any, any, any>>>(name: N, columns: C, options?: {
+  cache?: TableCacheConfig;
+}): TableDefinition<{ [K in keyof C]: C[K]["__type"] }, BoundColumns<C, N>, N, ExtractDeferredRefs<BoundColumns<C, N>>>;
 //#endregion
 export { table };
 //# sourceMappingURL=table.d.cts.map

package/dist/schema/table.d.mts

@@ -1,4 +1,4 @@
-import { DeferredRefMeta, TableDefinition } from "../types.mjs";
+import { DeferredRefMeta, TableCacheConfig, TableDefinition } from "../types.mjs";
 import { ColumnBuilder } from "./column.mjs";
 
 //#region src/schema/table.d.ts
@@ -11,7 +11,9 @@ type ExtractDeferredRefs<C extends Record<string, ColumnBuilder<any, any, any, a
  * @param {Record<string, ColumnBuilder<any>>} columns - Column definitions
  * @returns {TableDefinition<T, C>} The table definition object with column accessors
  */
-declare function table<N extends string, C extends Record<string, ColumnBuilder<any, any, any, any>>>(name: N, columns: C): TableDefinition<{ [K in keyof C]: C[K]["__type"] }, BoundColumns<C, N>, N, ExtractDeferredRefs<BoundColumns<C, N>>>;
+declare function table<N extends string, C extends Record<string, ColumnBuilder<any, any, any, any>>>(name: N, columns: C, options?: {
+  cache?: TableCacheConfig;
+}): TableDefinition<{ [K in keyof C]: C[K]["__type"] }, BoundColumns<C, N>, N, ExtractDeferredRefs<BoundColumns<C, N>>>;
 //#endregion
 export { table };
 //# sourceMappingURL=table.d.mts.map

package/dist/schema/table.mjs

@@ -5,7 +5,7 @@
 * @param {Record<string, ColumnBuilder<any>>} columns - Column definitions
 * @returns {TableDefinition<T, C>} The table definition object with column accessors
 */
-function table(name, columns) {
+function table(name, columns, options) {
 	const columnsArray = [];
 	const deferredRefs = [];
 	const columnMap = {};
@@ -29,6 +29,7 @@ function table(name, columns) {
 		__name: name,
 		__columns: columnsArray,
 		__columnMap: columnMap,
+		__cache: options?.cache,
 		__deferredRefs: deferredRefs,
 		...columns
 	};

package/dist/schema/table.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"table.mjs","names":[],"sources":["../../src/schema/table.ts"],"sourcesContent":["import type { ColumnMetadata, DeferredRefMeta, 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): 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    __deferredRefs: deferredRefs,\n    ...columns,\n  };\n\n  return def as any;\n}\n"],"mappings":";;;;;;;AA6BA,SAAgB,MAId,MACA,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;;AAYlC,QATY;EACV,SAAS;EACT,QAAQ;EACR,WAAW;EACX,aAAa;EACb,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/types.d.cts

@@ -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,74 @@ 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>[];
+  /**
+   * 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 to run on initialization */
   migrations?: any[];
+  /** 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 +237,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 +262,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 +303,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 +323,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.cts.map

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,74 @@ 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>[];
+  /**
+   * 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 to run on initialization */
   migrations?: any[];
+  /** 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 +237,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 +262,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 +303,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 +323,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