locality-idb 0.5.1 → 0.6.0

package/README.md

@@ -1,5 +1,7 @@
 # Locality IDB
 
+> **SQL**-like query builder for [**IndexedDB**](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB) with [**Drizzle**](https://github.com/drizzle-team/drizzle-orm)-style API
+
 <!-- markdownlint-disable-file MD024 -->
 
 <div align="center">
@@ -11,8 +13,6 @@
 <!-- ![bundle](https://img.shields.io/bundlephobia/minzip/locality-idb) -->
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)
 
-## SQL-like query builder for IndexedDB with Drizzle-style API
-
 [Documentation](#-api-reference) • [Examples](#-usage) • [Contributing](#-contributing)
 
 </div>
@@ -21,7 +21,7 @@
 
 ## ⚠️ Beta Status
 
->This package is currently in **beta development**. The API is subject to change. Use in production at your own risk.
+>This development of the package is currently in **beta stage**. The API is subject to change. Use in production at your own risk.
 
 ---
 
@@ -496,7 +496,7 @@ const query = db.delete('users');
 
 ### Schema Functions
 
-#### `defineSchema<T>(schema: T): Schema<T>`
+#### `defineSchema<Schema extends ColumnRecord, Keys extends keyof Schema>(schema: Schema): SchemaRecord<Schema, Keys>`
 
 Defines a database schema from an object mapping table names to column definitions.
 

package/dist/index.cjs

@@ -9,12 +9,12 @@ function isString(value) {
 function isInteger(value) {
 	return isNumber(value) && Number.isInteger(value);
 }
-function isPositiveInteger(value) {
-	return isInteger(value) && value > 0;
-}
 function isBoolean(value) {
 	return typeof value === "boolean";
 }
+function isBigInt(value) {
+	return typeof value === "bigint";
+}
 function isNonEmptyString(value) {
 	return isString(value) && value?.length > 0;
 }
@@ -33,9 +33,35 @@ function isObject(value) {
 function isNotEmptyObject(value) {
 	return isObject(value) && Object.keys(value)?.length > 0;
 }
+function isDate(value) {
+	return value instanceof Date;
+}
 function isArrayOfType(value, typeCheck) {
 	return isArray(value) && value?.every(typeCheck);
 }
+function isSet(value) {
+	return value instanceof Set;
+}
+function isMap(value) {
+	return value instanceof Map;
+}
+
+//#endregion
+//#region node_modules/.pnpm/nhb-toolbox@4.28.66/node_modules/nhb-toolbox/dist/esm/string/utilities.js
+const extractNumbersFromString = (input) => {
+	return (input.match(/\d+/g) || [])?.map(Number);
+};
+
+//#endregion
+//#region node_modules/.pnpm/nhb-toolbox@4.28.66/node_modules/nhb-toolbox/dist/esm/guards/specials.js
+function isUUID(value) {
+	const h = "[0-9a-f]";
+	const expr = new RegExp(`^${h}{8}-${h}{4}-[1-8]${h}{3}-[89ab]${h}{3}-${h}{12}$`, "i");
+	return isString(value) && expr.test(value);
+}
+function isNumericString(value) {
+	return isString(value) && value?.trim() !== "" && Number.isFinite(Number(value));
+}
 
 //#endregion
 //#region node_modules/.pnpm/nhb-toolbox@4.28.66/node_modules/nhb-toolbox/dist/esm/array/sort.js
@@ -145,7 +171,7 @@ var Column = class {
 			"integer",
 			"float",
 			"number"
-		].includes(colType.toLowerCase())) throw new Error(`auto() can only be used with integer columns, got: ${colType}`);
+		].includes(colType)) throw new Error(`auto() can only be used with integer columns, got: ${colType}`);
 		this[IsAutoInc] = true;
 		return this;
 	}
@@ -178,7 +204,7 @@ var Table = class {
 //#endregion
 //#region src/factory.ts
 /**
-* * Opens an `IndexedDB` database with the specified stores.
+* * Opens an `IndexedDB` database instance with the specified stores.
 * @param name Database name
 * @param stores Array of store configurations
 * @param version Database version (default is `1`)
@@ -245,6 +271,122 @@ function getTimestamp(value) {
 	if (isNaN(date.getTime())) date = /* @__PURE__ */ new Date();
 	return date.toISOString();
 }
+/**
+* * Check if a value is a valid Timestamp string in ISO 8601 format
+* @param value The value to check
+* @returns `true` if the value is a valid Timestamp, otherwise `false`
+*/
+function isTimestamp(value) {
+	return isNonEmptyString(value) && value.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/) !== null;
+}
+
+//#endregion
+//#region src/validators.ts
+/**
+* * Validate if a value matches the specified column data type
+* @param type The column data type
+* @param value The value to validate
+* @returns `null` if valid, otherwise an error message string
+*/
+function validateColumnType(type, value) {
+	const strVal = JSON.stringify(value);
+	switch (type) {
+		case "int":
+			if (isInteger(type)) return null;
+			return `'${strVal}' is not an integer`;
+		case "float":
+		case "number":
+			if (isNumber(value)) return null;
+			return `'${strVal}' is not a ${type === "float" ? "float " : ""}number`;
+		case "numeric":
+			if (isNumericString(value) || isNumber(value)) return null;
+			return `'${strVal}' is not a numeric value`;
+		case "bigint":
+			if (isBigInt(value)) return null;
+			return `'${strVal}' is not a bigint`;
+		case "text":
+		case "string":
+			if (isString(value)) return null;
+			return `'${strVal}' is not a ${type === "text" ? "text " : ""}string`;
+		case "timestamp":
+			if (isTimestamp(value)) return null;
+			return `'${strVal}' is not a timestamp string`;
+		case "uuid":
+			if (isUUID(value)) return null;
+			return `'${strVal}' is not a UUID string`;
+		case "bool":
+		case "boolean":
+			if (isBoolean(value)) return null;
+			return `'${strVal}' is not a boolean`;
+		case "array":
+			if (isArray(value)) return null;
+			return `'${strVal}' is not an array`;
+		case "list":
+			if (isArray(value)) return null;
+			return `'${strVal}' is not a list`;
+		case "tuple":
+			if (isArray(value)) return null;
+			return `'${strVal}' is not a tuple`;
+		case "set":
+			if (isSet(value)) return null;
+			return `'${strVal}' is not a set`;
+		case "object":
+			if (isObject(value)) return null;
+			return `'${strVal}' is not an object`;
+		case "date":
+			if (isDate(value)) return null;
+			return `'${strVal}' is not a Date object`;
+		case "map":
+			if (isMap(value)) return null;
+			return `'${strVal}' is not a Map object`;
+		case "custom": return null;
+		default:
+			if (type.includes("varchar(")) {
+				if (isString(value)) {
+					const length = extractNumbersFromString(type)[0];
+					if (isNumber(length) && value.length <= length) return null;
+					return `'${strVal}' does not satisfy the constraint: varchar length ${length}`;
+				}
+				return `'${strVal}' is not a varchar string`;
+			}
+			if (type.includes("char(")) {
+				if (isString(value)) {
+					const length = extractNumbersFromString(type)[0];
+					if (isNumber(length) && value.length === length) return null;
+					return `'${strVal}' does not satisfy the constraint: char length ${length}`;
+				}
+				return `'${strVal}' is not a char string`;
+			}
+			return null;
+	}
+}
+/**
+* * Validate and prepare data for insertion or update based on column definitions
+*
+* @param data The data object to validate and prepare
+* @param columns The column definitions
+* @param keyPath The key path of the primary key column (if any)
+* @param forUpdate Whether the operation is an update (default: `false`)
+*
+* @returns The validated and prepared data object
+* @throws {TypeError} If any value does not match the expected column type
+*/
+function validateAndPrepareData(data, columns, keyPath, forUpdate = false) {
+	const prepared = { ...data };
+	if (columns) Object.entries(columns).forEach((entry) => {
+		const [fieldName, column] = entry;
+		const defaultValue = column[DefaultValue];
+		if (!(fieldName in prepared) && defaultValue !== void 0 && !forUpdate) prepared[fieldName] = defaultValue;
+		const columnType = column[ColumnType];
+		if (columnType === "uuid" && !(fieldName in prepared) && !forUpdate) prepared[fieldName] = uuidV4();
+		if (columnType === "timestamp" && !(fieldName in prepared) && !forUpdate) prepared[fieldName] = getTimestamp();
+		if (fieldName !== keyPath) {
+			const errorMsg = validateColumnType(columnType, prepared[fieldName]);
+			if (errorMsg) throw new TypeError(errorMsg);
+		}
+	});
+	return prepared;
+}
 
 //#endregion
 //#region src/query.ts
@@ -351,11 +493,13 @@ var InsertQuery = class {
 	#readyPromise;
 	#dataToInsert = [];
 	#columns;
-	constructor(table, dbGetter, readyPromise, columns) {
+	#keyPath;
+	constructor(table, dbGetter, readyPromise, columns, keyPath) {
 		this.#table = table;
 		this.#dbGetter = dbGetter;
 		this.#readyPromise = readyPromise;
 		this.#columns = columns;
+		this.#keyPath = keyPath;
 	}
 	/**
 	* @instance Sets the data to be inserted
@@ -378,15 +522,7 @@ var InsertQuery = class {
 			const insertedDocs = [];
 			const promises = this.#dataToInsert.map((data) => {
 				return new Promise((res, rej) => {
-					const updated = { ...data };
-					if (this.#columns) Object.entries(this.#columns).forEach(([fieldName, column]) => {
-						const defaultValue = column[DefaultValue];
-						if (!(fieldName in updated) && defaultValue !== void 0) updated[fieldName] = defaultValue;
-						const columnType = column[ColumnType];
-						if (columnType === "uuid" && !(fieldName in updated)) updated[fieldName] = uuidV4();
-						if (columnType === "timestamp" && !(fieldName in updated)) updated[fieldName] = getTimestamp();
-					});
-					const request = store.add(updated);
+					const request = store.add(validateAndPrepareData(data, this.#columns, this.#keyPath));
 					request.onsuccess = () => {
 						const key = request.result;
 						const getRequest = store.get(key);
@@ -411,10 +547,14 @@ var UpdateQuery = class {
 	#readyPromise;
 	#dataToUpdate;
 	#whereCondition;
-	constructor(table, dbGetter, readyPromise) {
+	#columns;
+	#keyPath;
+	constructor(table, dbGetter, readyPromise, columns, keyPath) {
 		this.#table = table;
 		this.#dbGetter = dbGetter;
 		this.#readyPromise = readyPromise;
+		this.#columns = columns;
+		this.#keyPath = keyPath;
 	}
 	/**
 	* @instance Sets the data to be updated
@@ -448,10 +588,10 @@ var UpdateQuery = class {
 				if (this.#whereCondition) rows = rows.filter(this.#whereCondition);
 				const updatePromises = rows.map((row) => {
 					return new Promise((res, rej) => {
-						const updatedRow = {
+						const updatedRow = validateAndPrepareData({
 							...row,
 							...this.#dataToUpdate
-						};
+						}, this.#columns, this.#keyPath, true);
 						const putRequest = store.put(updatedRow);
 						putRequest.onsuccess = () => {
 							updateCount++;
@@ -561,17 +701,22 @@ var DeleteQuery = class {
 var Locality = class {
 	#name;
 	#schema;
-	#version;
+	#keyPath;
+	version;
 	#db;
+	#version;
 	#readyPromise;
 	constructor(config) {
 		this.#name = config.dbName;
 		this.#schema = config.schema;
-		this.#version = config.version;
 		const store = this.#buildStoresConfig();
-		this.#readyPromise = openDBWithStores(this.#name, store, this.#version).then((db) => {
+		this.#keyPath = store.find((s) => s.autoIncrement)?.keyPath;
+		this.#readyPromise = openDBWithStores(this.#name, store, config.version).then((db) => {
 			this.#db = db;
+		}).finally(() => {
+			this.#version = this.#db?.version;
 		});
+		this.version = this.#version ?? config.version;
 	}
 	/** Build store configurations from schema. */
 	#buildStoresConfig() {
@@ -602,14 +747,14 @@ var Locality = class {
 	* @param table Table name.
 	*/
 	insert(table) {
-		return new InsertQuery(table, () => this.#db, this.#readyPromise, this.#schema[table].columns);
+		return new InsertQuery(table, () => this.#db, this.#readyPromise, this.#schema[table].columns, this.#keyPath);
 	}
 	/**
 	* @instance Update records in a table.
 	* @param table Table name.
 	*/
 	update(table) {
-		return new UpdateQuery(table, () => this.#db, this.#readyPromise);
+		return new UpdateQuery(table, () => this.#db, this.#readyPromise, this.#schema[table].columns, this.#keyPath);
 	}
 	/**
 	* @instance Delete records from a table.
@@ -716,11 +861,12 @@ const column = {
 	int: () => new Column("int"),
 	float: () => new Column("float"),
 	number: () => new Column("number"),
+	numeric: () => new Column("numeric"),
 	bigint: () => new Column("bigint"),
 	text: () => new Column("text"),
 	string: () => new Column("string"),
-	char: (l) => new Column(`char(${isPositiveInteger(l) ? l : "0"})`),
-	varchar: (l) => new Column(`varchar(${isPositiveInteger(l) ? l : "0"})`),
+	char: (length = 8) => new Column(`char(${length})`),
+	varchar: (length = 32) => new Column(`varchar(${length})`),
 	uuid: () => new Column("uuid"),
 	timestamp: () => new Column("timestamp"),
 	bool: () => new Column("bool"),
@@ -739,6 +885,8 @@ exports.Locality = Locality;
 exports.column = column;
 exports.defineSchema = defineSchema;
 exports.getTimestamp = getTimestamp;
+exports.isTimestamp = isTimestamp;
 exports.openDBWithStores = openDBWithStores;
 exports.table = table;
-exports.uuidV4 = uuidV4;
+exports.uuidV4 = uuidV4;
+exports.validateColumnType = validateColumnType;

package/dist/index.d.cts

@@ -16,16 +16,16 @@ declare const IsUnique: unique symbol;
 /** Symbol key for default value */
 declare const DefaultValue: unique symbol;
 /** @class Represents a column definition. */
-declare class Column<T = any> {
+declare class Column<T = any, TName extends TypeName = TypeName> {
   [$ColumnType]: T;
-  [ColumnType]: string;
+  [ColumnType]: TName;
   [IsPrimaryKey]?: boolean;
   [IsAutoInc]?: boolean;
   [IsOptional]?: boolean;
   [IsIndexed]?: boolean;
   [IsUnique]?: boolean;
   [DefaultValue]?: T;
-  constructor(type: string);
+  constructor(type: TName);
   /** @instance Marks column as primary key */
   pk(): this & {
     [IsPrimaryKey]: true;
@@ -103,6 +103,8 @@ type Branded<T, B> = T & $Brand<B>;
  * @note Technically, this uses intersection with primitive base types (`string & {}` or `number & {}`) to retain IntelliSense while avoiding type narrowing.
  */
 type LooseLiteral<T extends string | number> = T | (T extends string ? string & {} : number & {});
+/** Union of `number` and numeric string */
+type Numeric = number | `${number}`;
 /**
  * * A readonly array of elements of type `T`.
  *
@@ -188,6 +190,28 @@ interface DateLike {
 }
 /** Advanced types to exclude from counting as object key */
 type AdvancedTypes = Array<unknown> | File | FileList | Blob | Date | RegExp | Constructor | DateLike | WeakMap<WeakKey, unknown> | WeakSet<WeakKey> | Map<unknown, unknown> | Set<unknown> | Function | GenericFn | VoidFn | AsyncFunction<unknown> | Promise<unknown> | Error | EvalError | RangeError | ReferenceError | SyntaxError | TypeError | URIError | bigint | symbol;
+/**
+ * * Extracts the parameters of the first overload of a function type `T`.
+ *
+ * @template T - The function type to extract parameters from.
+ *
+ * @returns A tuple type representing the parameters of the first overload of `T`.
+ *
+ * @example
+ * type Fn = {
+ *   (a: number, b: string): void;
+ *   (x: boolean): void;
+ * };
+ *
+ * type Params = FirstOverloadParams<Fn>; // [a: number, b: string]
+ */
+type FirstOverloadParams<T> = T extends ({
+  (a1: infer P1, ...args: infer P2): any;
+  (...args: any[]): any;
+}) ? [P1, ...P2] : T extends ({
+  (...args: infer P): any;
+  (...args: any[]): any;
+}) ? P : T extends ((...args: infer P) => any) ? P : never;
 /**
  * * Maps all values of object `T` to a fixed type `R`, keeping original keys.
  *
@@ -235,8 +259,6 @@ type $UUIDVersion = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 type UUIDVersion = `v${$UUIDVersion}`;
 /** General 5 parts UUID string as {@link Branded} type */
 type UUID<V extends UUIDVersion> = Branded<$UUID, V>;
-/** Schema definition type */
-type SchemaDefinition<T extends ColumnDefinition = ColumnDefinition> = Record<string, Table<T>>;
 /** Locality database configuration type */
 type LocalityConfig<DB extends string, V extends number, S extends SchemaDefinition> = {
   /** Database name */dbName: DB; /** Database version */
@@ -245,6 +267,12 @@ type LocalityConfig<DB extends string, V extends number, S extends SchemaDefinit
 };
 /** Column definition type */
 type ColumnDefinition<T = any> = Record<string, Column<T>>;
+/** Record of column definitions */
+type ColumnRecord = Record<string, ColumnDefinition>;
+/** Schema record type mapping table names to {@link Table} instances */
+type SchemaRecord<T extends ColumnRecord, Keys extends keyof T> = { [K in Keys]: Table<T[K]> };
+/** Schema definition type */
+type SchemaDefinition<T extends ColumnDefinition = ColumnDefinition> = Record<string, Table<T>>;
 /** Helper to reliably extract the generic type parameter from a Column using a symbol property. */
 type ExtractColumnType<C> = C extends {
   [$ColumnType]: infer U;
@@ -283,10 +311,12 @@ type InferInsertType<T extends Table> = Prettify<Omit<$InferRow<T['columns']>, $
 type InferUpdateType<T extends Table> = Prettify<Partial<Omit<$InferRow<T['columns']>, $InferPkField<T['columns']>>>>;
 /** Creates a type for select operations. */
 type InferSelectType<S extends Table> = Prettify<S extends infer T ? T extends Table<infer C> ? $InferRow<C> : never : never>;
+/** Column type strings used in {@link Column} definitions */
+type TypeName = LooseLiteral<'int' | 'float' | 'number' | 'numeric' | 'bigint' | 'text' | 'string' | 'uuid' | 'timestamp' | 'bool' | 'date' | 'object' | 'array' | 'list' | 'tuple' | 'set' | 'map' | 'custom'>;
 /** Store configuration type for {@link IndexedDB} */
 type StoreConfig = {
   /** Store name */name: string; /** Primary key path(s) */
-  keyPath?: string | string[]; /** Whether the primary key is auto-incrementing */
+  keyPath?: string; /** Whether the primary key is auto-incrementing */
   autoIncrement?: boolean;
 };
 //#endregion
@@ -336,7 +366,7 @@ declare class SelectQuery<T extends GenericObject, S = null> {
 declare class InsertQuery<Raw extends GenericObject, Inserted, Data extends GenericObject, Return extends (Inserted extends Array<infer _> ? Data[] : Data)> {
   #private;
   [IsArray]: boolean;
-  constructor(table: string, dbGetter: () => IDBDatabase, readyPromise: Promise<void>, columns?: ColumnDefinition);
+  constructor(table: string, dbGetter: () => IDBDatabase, readyPromise: Promise<void>, columns?: ColumnDefinition, keyPath?: string);
   /**
    * @instance Sets the data to be inserted
    * @param data Data object or array of data objects to insert
@@ -351,7 +381,7 @@ declare class InsertQuery<Raw extends GenericObject, Inserted, Data extends Gene
 /** @class Update query builder. */
 declare class UpdateQuery<T extends GenericObject, S extends Table> {
   #private;
-  constructor(table: string, dbGetter: () => IDBDatabase, readyPromise: Promise<void>);
+  constructor(table: string, dbGetter: () => IDBDatabase, readyPromise: Promise<void>, columns?: ColumnDefinition, keyPath?: string);
   /**
    * @instance Sets the data to be updated
    * @param values Values to update
@@ -425,6 +455,7 @@ declare class DeleteQuery<T extends GenericObject, Key extends keyof T> {
  */
 declare class Locality<DBName extends string = string, Version extends number = 1, Schema extends SchemaDefinition = SchemaDefinition> {
   #private;
+  readonly version: Version;
   constructor(config: LocalityConfig<DBName, Version, Schema>);
   /** @instance Waits for database initialization to complete. */
   ready(): Promise<void>;
@@ -453,7 +484,7 @@ declare class Locality<DBName extends string = string, Version extends number =
 //#endregion
 //#region src/factory.d.ts
 /**
- * * Opens an `IndexedDB` database with the specified stores.
+ * * Opens an `IndexedDB` database instance with the specified stores.
  * @param name Database name
  * @param stores Array of store configurations
  * @param version Database version (default is `1`)
@@ -494,7 +525,7 @@ declare function openDBWithStores(name: string, stores: StoreConfig[], version?:
  * type InsertPost = InferInsertType<typeof schema.posts>;
  * type UpdatePost = InferUpdateType<typeof schema.posts>;
  */
-declare function defineSchema<T extends Record<string, ColumnDefinition>, Keys extends keyof T>(schema: T): { [K in Keys]: Table<T[K]> };
+declare function defineSchema<Schema extends ColumnRecord, Keys extends keyof Schema>(schema: Schema): SchemaRecord<Schema, Keys>;
 /**
  * * Factory function to create a new {@link Table} instance.
  * @param name The name of the table.
@@ -550,51 +581,57 @@ declare const column: {
    * @returns A new {@link Column} instance for integers.
    * @remarks  column type is typically used for whole numbers.
    */
-  readonly int: () => Column<number>;
+  readonly int: () => Column<number, "int">;
   /**
    * Creates a float column.
    * @returns A new {@link Column} instance for floating-point numbers.
    * @remarks This column type is specifically for decimal numbers.
    */
-  readonly float: () => Column<number>;
+  readonly float: () => Column<number, "float">;
   /**
    * Creates a number column.
    * @returns A new {@link Column} instance for numbers.
    * @remarks This column type is used for both whole & floating-point numbers.
    */
-  readonly number: () => Column<number>;
+  readonly number: () => Column<number, "number">;
+  /**
+   * Creates a numeric (number or numeric string) column.
+   * @returns A new {@link Column} instance for numeric.
+   * @remarks This column type is used for both whole & floating-point numbers or numeric strings.
+   */
+  readonly numeric: () => Column<Numeric, "numeric">;
   /**
    * Creates a bigint column.
    * @returns A new {@link Column} instance for bigints.
    * @remarks This column type is used for large integers beyond the safe integer limit of JavaScript.
    */
-  readonly bigint: () => Column<bigint>;
+  readonly bigint: () => Column<bigint, "bigint">;
   /**
    * Creates a text column.
    * @returns A new {@link Column} instance for text.
    * @remarks This column type is used for large strings of text.
    */
-  readonly text: () => Column<string>;
+  readonly text: () => Column<string, "text">;
   /**
    * Creates a string column.
    * @returns A new {@link Column} instance for strings.
    * @remarks This column type is used for general string data.
    */
-  readonly string: () => Column<string>;
+  readonly string: () => Column<string, "string">;
   /**
    * Creates a char column with optional length.
-   * @param l Optional length of the char column.
+   * @param length Optional length of the char column. Defaults to `8`.
    * @returns A new {@link Column} instance for char.
    * @remarks This column type is used for fixed-length strings.
    */
-  readonly char: (l?: number) => Column<string>;
+  readonly char: <L extends number = 8>(length?: L) => Column<string, `char(${L})`>;
   /**
    * Creates a varchar column with optional length.
-   * @param l Optional length of the varchar column.
+   * @param length Optional length of the varchar column. Defaults to `32`.
    * @returns A new {@link Column} instance for varchar.
    * @remarks This column type is used for variable-length strings.
    */
-  readonly varchar: (l?: number) => Column<string>;
+  readonly varchar: <L extends number = 32>(length?: L) => Column<string, `varchar(${L})`>;
   /**
    * Creates a UUID column.
    * @returns A new {@link Column} instance for UUIDs.
@@ -603,7 +640,7 @@ declare const column: {
    * - UUIDs are typically used as unique identifiers.
    * - Automatically genrates UUID v4 values when no value is provided.
    */
-  readonly uuid: () => Column<`${string}-${string}-${string}-${string}-${string}`>;
+  readonly uuid: () => Column<`${string}-${string}-${string}-${string}-${string}`, "uuid">;
   /**
    * Creates a timestamp column.
    * @returns A new {@link Column} instance for timestamps.
@@ -611,55 +648,55 @@ declare const column: {
    * - This column type is used for storing date and time information in ISO 8601 format.
    * - Automatically generates the current timestamp when no value is provided.
    */
-  readonly timestamp: () => Column<Timestamp>;
+  readonly timestamp: () => Column<Timestamp, "timestamp">;
   /**
    * Creates a boolean column.
    * @returns A new {@link Column} instance for booleans.
    * @remarks This column type is used for true/false values.
    */
-  readonly bool: () => Column<boolean>;
+  readonly bool: () => Column<boolean, "bool">;
   /**
    * Creates a date column.
    * @returns A new {@link Column} instance for dates.
    * @remarks This column type is used for storing date values.
    */
-  readonly date: () => Column<Date>;
+  readonly date: () => Column<Date, "date">;
   /**
    * Creates an object column.
    * @returns A new {@link Column} instance for objects.
    * @remarks This column type is used for storing generic objects with string keys.
    */
-  readonly object: <Obj extends GenericObject>() => Column<Obj>;
+  readonly object: <Obj extends GenericObject>() => Column<Obj, "object">;
   /**
    * Creates an array column.
    * @returns A new {@link Column} instance for arrays.
    * @remarks This column type is used for storing arrays of any type.
    */
-  readonly array: <T = any>() => Column<T[]>;
+  readonly array: <T = any>() => Column<T[], "array">;
   /**
    * Creates a list column.
    * @returns A new {@link Column} instance for lists.
    * @remarks This column type is used for storing lists of any type.
    */
-  readonly list: <T = any>() => Column<List<T>>;
+  readonly list: <T = any>() => Column<List<T>, "list">;
   /**
    * Creates a tuple column.
    * @returns A new {@link Column} instance for tuples.
    * @remarks This column type is used for storing fixed-size arrays (tuples) of any type.
    */
-  readonly tuple: <T = any>() => Column<Tuple<T>>;
+  readonly tuple: <T = any>() => Column<Tuple<T>, "tuple">;
   /**
    * Creates a set column.
    * @returns A new {@link Column} instance for sets.
    * @remarks This column type is used for storing unique collections of any type.
    */
-  readonly set: <T = any>() => Column<Set<T>>;
+  readonly set: <T = any>() => Column<Set<T>, "set">;
   /**
    * Creates a map column.
    * @returns A new {@link Column} instance for maps.
    * @remarks This column type is used for storing key-value pairs of any type.
    */
-  readonly map: <K = any, V = any>() => Column<Map<K, V>>;
+  readonly map: <K = any, V = any>() => Column<Map<K, V>, "map">;
   /**
    * Creates a custom column.
    * @returns A new {@link Column} instance for custom data types.
@@ -668,7 +705,7 @@ declare const column: {
    * - You can specify the type when creating the column.
    * - No built-in serialization/deserialization is provided; you must handle it yourself.
    */
-  readonly custom: <T = any>() => Column<T>;
+  readonly custom: <T = any>() => Column<T, "custom">;
 };
 //#endregion
 //#region src/utils.d.ts
@@ -685,5 +722,20 @@ declare function uuidV4(uppercase?: boolean): UUID<'v4'>;
  * @return Timestamp string in ISO 8601 format
  */
 declare function getTimestamp(value?: string | number | Date): Timestamp;
+/**
+ * * Check if a value is a valid Timestamp string in ISO 8601 format
+ * @param value The value to check
+ * @returns `true` if the value is a valid Timestamp, otherwise `false`
+ */
+declare function isTimestamp(value: unknown): value is Timestamp;
+//#endregion
+//#region src/validators.d.ts
+/**
+ * * Validate if a value matches the specified column data type
+ * @param type The column data type
+ * @param value The value to validate
+ * @returns `null` if valid, otherwise an error message string
+ */
+declare function validateColumnType<T extends TypeName>(type: T, value: unknown): string | null;
 //#endregion
-export { $InferAutoInc, $InferDefault, $InferOptional, $InferPkField, $InferRow, $InferTimestamp, $InferUUID, $UUID, $UUIDVersion, $UnionToIntersection, AdvancedTypes, ArrayToTuple, AsyncFunction, BasicPrimitive, Branded, type Column, ColumnDefinition, Constructor, DateLike, GenericFn, GenericObject, InferInsertType, InferSelectType, InferUpdateType, List, Locality, LocalityConfig, LooseLiteral, MapObjectValues, NestedPrimitiveKey, NormalPrimitive, Prettify, Primitive, SchemaDefinition, SelectFields, SortDirection, StoreConfig, type Table, Timestamp, Tuple, UUID, UUIDVersion, VoidFn, column, defineSchema, getTimestamp, openDBWithStores, table, uuidV4 };
+export { $InferAutoInc, $InferDefault, $InferOptional, $InferPkField, $InferRow, $InferTimestamp, $InferUUID, $UUID, $UUIDVersion, $UnionToIntersection, AdvancedTypes, ArrayToTuple, AsyncFunction, BasicPrimitive, Branded, type Column, ColumnDefinition, ColumnRecord, Constructor, DateLike, FirstOverloadParams, GenericFn, GenericObject, InferInsertType, InferSelectType, InferUpdateType, List, Locality, LocalityConfig, LooseLiteral, MapObjectValues, NestedPrimitiveKey, NormalPrimitive, Numeric, Prettify, Primitive, SchemaDefinition, SchemaRecord, SelectFields, SortDirection, StoreConfig, type Table, Timestamp, Tuple, TypeName, UUID, UUIDVersion, VoidFn, column, defineSchema, getTimestamp, isTimestamp, openDBWithStores, table, uuidV4, validateColumnType };