locality-idb 0.6.0 → 0.6.1

package/README.md

@@ -11,9 +11,9 @@
 ![license](https://img.shields.io/npm/l/locality-idb)
 ![beta](https://img.shields.io/badge/status-beta-orange)
 <!-- ![bundle](https://img.shields.io/bundlephobia/minzip/locality-idb) -->
-![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)
+<!-- ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue) -->
 
-[Documentation](#-api-reference) • [Examples](#-usage) • [Contributing](#-contributing)
+[API Reference](#-api-reference) • [Examples](#-usage) • [Contributing](#-contributing)
 
 </div>
 
@@ -46,6 +46,7 @@
   - [Column Modifiers](#column-modifiers)
   - [Query Methods](#query-methods)
   - [Utility Functions](#utility-functions)
+  - [Validation](#validation)
 - [Type System](#-type-system)
 - [Contributing](#-contributing)
 - [License](#-license)
@@ -62,6 +63,7 @@
 - 🎨 **Schema-First**: Define your database schema with a simple, declarative API
 - ⚡ **Promise-Based**: Fully async/await compatible
 - 🛠️ **Rich Column Types**: Support for various data types including custom types
+- ✅ **Built-in Validation**: Automatic data type validation for built-in column types during insert and update operations
 
 ---
 
@@ -166,24 +168,26 @@ const schema = defineSchema({
 
 Locality IDB supports a wide range of column types:
 
-| Type                             | Description                          | Example                            |
-| -------------------------------- | ------------------------------------ | ---------------------------------- |
-| `int()` / `number()` / `float()` | Numeric values                       | `column.int()`                     |
-| `bigint()`                       | Large integers                       | `column.bigint()`                  |
-| `text()` / `string()`            | Text strings                         | `column.text()`                    |
-| `char(length?)`                  | Fixed-length string                  | `column.char(10)`                  |
-| `varchar(length?)`               | Variable-length string               | `column.varchar(255)`              |
-| `bool()`                         | Boolean values                       | `column.bool()`                    |
-| `date()`                         | Date objects                         | `column.date()`                    |
-| `timestamp()`                    | ISO 8601 timestamps (auto-generated) | `column.timestamp()`               |
-| `uuid()`                         | UUID strings (auto-generated v4)     | `column.uuid()`                    |
-| `object<T>()`                    | Generic objects                      | `column.object<UserData>()`        |
-| `array<T>()`                     | Arrays                               | `column.array<number>()`           |
-| `list<T>()`                      | Read-only arrays                     | `column.list<string>()`            |
-| `tuple<T>()`                     | Fixed-size tuples                    | `column.tuple<[string, number]>()` |
-| `set<T>()`                       | Sets                                 | `column.set<string>()`             |
-| `map<K,V>()`                     | Maps                                 | `column.map<string, number>()`     |
-| `custom<T>()`                    | Custom types                         | `column.custom<MyType>()`          |
+| Type                   | Description                                                | Example                            |
+| ---------------------- | ---------------------------------------------------------- | ---------------------------------- |
+| `number()` / `float()` | Numeric values (integer or float)                          | `column.int()`                     |
+| `int()`                | Numeric values (only integer is allowed)                   | `column.int()`                     |
+| `numeric()`            | Number or numeric string                                   | `column.numeric()`                 |
+| `bigint()`             | Large integers                                             | `column.bigint()`                  |
+| `text()` / `string()`  | Text strings                                               | `column.text()`                    |
+| `char(length?)`        | Fixed-length string                                        | `column.char(10)`                  |
+| `varchar(length?)`     | Variable-length string                                     | `column.varchar(255)`              |
+| `bool()` / `boolean()` | Boolean values                                             | `column.bool()`                    |
+| `date()`               | Date objects                                               | `column.date()`                    |
+| `timestamp()`          | ISO 8601 timestamps ([auto-generated](#utility-functions)) | `column.timestamp()`               |
+| `uuid()`               | UUID strings ([auto-generated](#utility-functions) v4)     | `column.uuid()`                    |
+| `object<T>()`          | Generic objects                                            | `column.object<UserData>()`        |
+| `array<T>()`           | Arrays                                                     | `column.array<number>()`           |
+| `list<T>()`            | Read-only arrays                                           | `column.list<string>()`            |
+| `tuple<T>()`           | Fixed-size tuples                                          | `column.tuple<[string, number]>()` |
+| `set<T>()`             | Sets                                                       | `column.set<string>()`             |
+| `map<K,V>()`           | Maps                                                       | `column.map<string, number>()`     |
+| `custom<T>()`          | Custom types                                               | `column.custom<MyType>()`          |
 
 ### Type Inference
 
@@ -779,6 +783,27 @@ const fromUnix = getTimestamp(1704067200000); // "2024-01-01T00:00:00.000Z"
 const fallback = getTimestamp('invalid'); // Current timestamp
 ```
 
+#### `isTimestamp(value: unknown): value is Timestamp`
+
+Checks if a value is a valid Timestamp string in ISO 8601 format.
+
+**Parameters:**
+
+- `value`: The value to check
+
+**Returns:** `true` if the value is a valid Timestamp, otherwise `false`
+
+**Example:**
+
+```typescript
+import { isTimestamp } from 'locality-idb';
+
+isTimestamp('2026-01-29T12:34:56.789Z'); // true
+isTimestamp('2026-01-29'); // false (not full ISO 8601)
+isTimestamp('invalid'); // false
+isTimestamp(123); // false
+```
+
 #### `openDBWithStores(name: string, stores: StoreConfig[], version?: number): Promise<IDBDatabase>`
 
 Opens an IndexedDB database with specified stores (low-level API).
@@ -813,6 +838,88 @@ const db = await openDBWithStores(
 
 ---
 
+### Validation
+
+Locality IDB includes built-in validation that automatically validates data types for built-in column types during insert and update operations based on your schema definitions.
+
+#### Automatic Validation
+
+When you insert or update records, Locality IDB automatically validates that the values match their expected column types:
+
+```typescript
+const schema = defineSchema({
+  users: {
+    id: column.int().pk().auto(),
+    name: column.text(),
+    age: column.int(),
+    email: column.varchar(255),
+  },
+});
+
+const db = new Locality({ dbName: 'app', schema });
+
+// ✅ Valid - all types match
+await db.insert('users').values({ name: 'Alice', age: 25, email: 'alice@example.com' }).run();
+
+// ❌ Throws TypeError - age must be an integer
+await db.insert('users').values({ name: 'Bob', age: 'twenty', email: 'bob@example.com' }).run();
+
+// ❌ Throws TypeError - email exceeds varchar(255) length
+await db.insert('users').values({ name: 'Charlie', age: 30, email: 'a'.repeat(300) }).run();
+```
+
+#### `validateColumnType<T>(type: T, value: unknown): string | null`
+
+Manually validate if a value matches the specified column data type.
+
+**Parameters:**
+
+- `type`: The column data type (e.g., `'int'`, `'text'`, `'uuid'`, `'varchar(255)'`)
+- `value`: The value to validate
+
+**Returns:** `null` if valid, otherwise an error message string
+
+**Example:**
+
+```typescript
+import { validateColumnType } from 'locality-idb';
+
+validateColumnType('int', 42);          // null (valid)
+validateColumnType('int', 'hello');     // "'\"hello\"' is not an integer"
+validateColumnType('text', 'hello');    // null (valid)
+validateColumnType('uuid', '550e8400-e29b-41d4-a716-446655440000'); // null (valid)
+validateColumnType('varchar(5)', 'hi'); // null (valid)
+validateColumnType('varchar(5)', 'hello world'); // error message
+validateColumnType('numeric', 42);      // null (valid)
+validateColumnType('numeric', '3.14');  // null (valid)
+validateColumnType('numeric', 'abc');   // error message
+```
+
+#### Validated Column Types
+
+The following column types are validated:
+
+| Type                       | Validation Rule                                                             |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `int`                      | Must be an integer                                                          |
+| `float` / `number`         | Must be a number                                                            |
+| `numeric`                  | Must be a number or numeric string                                          |
+| `bigint`                   | Must be a BigInt                                                            |
+| `text` / `string`          | Must be a string                                                            |
+| `char(n)`                  | Must be a string with exactly `n` characters                                |
+| `varchar(n)`               | Must be a string with at most `n` characters                                |
+| `bool` / `boolean`         | Must be a boolean                                                           |
+| `uuid`                     | Must be a valid UUID string                                                 |
+| `timestamp`                | Must be a valid ISO 8601 timestamp string                                   |
+| `date`                     | Must be a Date object                                                       |
+| `array` / `list` / `tuple` | Must be an array                                                            |
+| `set`                      | Must be a Set                                                               |
+| `map`                      | Must be a Map                                                               |
+| `object`                   | Must be an object                                                           |
+| `custom`                   | No validation (always passes, custom validation integration coming soon...) |
+
+---
+
 ## 🔧 Type System
 
 Locality IDB provides comprehensive TypeScript support:

package/dist/index.cjs

@@ -870,6 +870,7 @@ const column = {
 	uuid: () => new Column("uuid"),
 	timestamp: () => new Column("timestamp"),
 	bool: () => new Column("bool"),
+	boolean: () => new Column("boolean"),
 	date: () => new Column("date"),
 	object: () => new Column(`object`),
 	array: () => new Column(`array`),

package/dist/index.d.cts

@@ -312,7 +312,7 @@ type InferUpdateType<T extends Table> = Prettify<Partial<Omit<$InferRow<T['colum
 /** 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'>;
+type TypeName<L extends number = number> = LooseLiteral<'int' | 'float' | 'number' | 'numeric' | 'bigint' | 'text' | 'string' | `char(${L})` | `varchar(${L})` | 'uuid' | 'timestamp' | 'bool' | 'boolean' | 'date' | 'object' | 'array' | 'list' | 'tuple' | 'set' | 'map' | 'custom'>;
 /** Store configuration type for {@link IndexedDB} */
 type StoreConfig = {
   /** Store name */name: string; /** Primary key path(s) */
@@ -650,11 +650,17 @@ declare const column: {
    */
   readonly timestamp: () => Column<Timestamp, "timestamp">;
   /**
-   * Creates a boolean column.
+   * Creates a boolean column. Same as {@link column.boolean boolean}.
    * @returns A new {@link Column} instance for booleans.
    * @remarks This column type is used for true/false values.
    */
   readonly bool: () => Column<boolean, "bool">;
+  /**
+   * Creates a boolean column. Same as {@link column.bool bool}.
+   * @returns A new {@link Column} instance for booleans.
+   * @remarks This column type is used for true/false values.
+   */
+  readonly boolean: () => Column<boolean, "boolean">;
   /**
    * Creates a date column.
    * @returns A new {@link Column} instance for dates.

package/dist/index.d.mts

@@ -312,7 +312,7 @@ type InferUpdateType<T extends Table> = Prettify<Partial<Omit<$InferRow<T['colum
 /** 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'>;
+type TypeName<L extends number = number> = LooseLiteral<'int' | 'float' | 'number' | 'numeric' | 'bigint' | 'text' | 'string' | `char(${L})` | `varchar(${L})` | 'uuid' | 'timestamp' | 'bool' | 'boolean' | 'date' | 'object' | 'array' | 'list' | 'tuple' | 'set' | 'map' | 'custom'>;
 /** Store configuration type for {@link IndexedDB} */
 type StoreConfig = {
   /** Store name */name: string; /** Primary key path(s) */
@@ -650,11 +650,17 @@ declare const column: {
    */
   readonly timestamp: () => Column<Timestamp, "timestamp">;
   /**
-   * Creates a boolean column.
+   * Creates a boolean column. Same as {@link column.boolean boolean}.
    * @returns A new {@link Column} instance for booleans.
    * @remarks This column type is used for true/false values.
    */
   readonly bool: () => Column<boolean, "bool">;
+  /**
+   * Creates a boolean column. Same as {@link column.bool bool}.
+   * @returns A new {@link Column} instance for booleans.
+   * @remarks This column type is used for true/false values.
+   */
+  readonly boolean: () => Column<boolean, "boolean">;
   /**
    * Creates a date column.
    * @returns A new {@link Column} instance for dates.

package/dist/index.iife.js

@@ -872,6 +872,7 @@ var LocalityIDB = (function(exports) {
 		uuid: () => new Column("uuid"),
 		timestamp: () => new Column("timestamp"),
 		bool: () => new Column("bool"),
+		boolean: () => new Column("boolean"),
 		date: () => new Column("date"),
 		object: () => new Column(`object`),
 		array: () => new Column(`array`),

package/dist/index.mjs

@@ -869,6 +869,7 @@ const column = {
 	uuid: () => new Column("uuid"),
 	timestamp: () => new Column("timestamp"),
 	bool: () => new Column("bool"),
+	boolean: () => new Column("boolean"),
 	date: () => new Column("date"),
 	object: () => new Column(`object`),
 	array: () => new Column(`array`),

package/dist/index.umd.js

@@ -875,6 +875,7 @@
 		uuid: () => new Column("uuid"),
 		timestamp: () => new Column("timestamp"),
 		bool: () => new Column("bool"),
+		boolean: () => new Column("boolean"),
 		date: () => new Column("date"),
 		object: () => new Column(`object`),
 		array: () => new Column(`array`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locality-idb",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "SQL-like query builder for IndexedDB with Drizzle-style API",
   "type": "module",
   "sideEffects": false,