locality-idb 1.2.0 → 1.3.0

package/README.md

@@ -16,14 +16,14 @@
 
 [API Reference](#-api-reference) • [Examples](#-usage) • [Contributing](CONTRIBUTING.md)
 
-</div>
-
 ---
 
 ## Why Locality IDB?
 
 [**IndexedDB**](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB) is a powerful browser-native database, but its low-level API can be cumbersome and complex to work with. `Locality IDB` simplifies `IndexedDB` interactions by providing a modern, type-safe, and SQL-like query builder inspired by [**Drizzle ORM**](https://github.com/drizzle-team/drizzle-orm).
 
+</div>
+
 ---
 
 ## 📋 Table of Contents
@@ -41,6 +41,8 @@
   - [Select/Query Records](#selectquery-records)
   - [Update Records](#update-records)
   - [Delete Records](#delete-records)
+  - [Transactions](#transactions)
+  - [Export Database](#export-database)
 - [API Reference](#-api-reference)
   - [Locality Class](#locality-class)
   - [Schema Functions](#schema-functions)
@@ -61,9 +63,11 @@
 - 📦 **Zero Dependencies**: Lightweight with only development dependencies
 - 🔄 **Auto-Generation**: Automatic UUID and timestamp generation
 - 🎨 **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
+- 🔧 **Custom Validators**: Define custom validation logic for columns to enforce complex rules
+- 🔒 **Atomic Transactions**: Execute multiple operations across tables with automatic rollback on failure
+- 📤 **Database Export**: Export database data as JSON for backup, migration, or debugging
 
 ---
 
@@ -205,6 +209,8 @@ Locality IDB supports a wide range of column types:
 | `text()` / `string()`  | Text strings                                               | `column.text()`                  |
 | `char(length?)`        | Fixed-length string                                        | `column.char(10)`                |
 | `varchar(length?)`     | Variable-length string                                     | `column.varchar(255)`            |
+| `email()`              | Email strings                                              | `column.email()`                 |
+| `url()`                | URL strings                                                | `column.url()`                   |
 | `bool()` / `boolean()` | Boolean values                                             | `column.bool()`                  |
 | `date()`               | Date objects                                               | `column.date()`                  |
 | `timestamp()`          | ISO 8601 timestamps ([auto-generated](#utility-functions)) | `column.timestamp()`             |
@@ -251,7 +257,7 @@ const productId: ProductId = 2 as ProductId;
 // userId = productId; // ❌ Type error!
 ```
 
-##### String Types (`text`, `string`, `char`, `varchar`)
+##### String Types (`text`, `string`, `char`, `varchar`, `email`, `url`)
 
 ```typescript
 // Literal unions for enum-like behavior
@@ -277,8 +283,40 @@ const profileSchema = defineSchema({
     website: column.varchar<URL>(500).optional(),
   },
 });
+
+// or use specialized `email` & `url` methods + types with built-in validation
+const advancedProfileSchema = defineSchema({
+  profiles: {
+    id: column.int().pk().auto(),
+    email: column.email().unique(), // Validates emails
+    website: column.url().optional(), // Validates URLs (internally uses URL constructor)
+  },
+});
+```
+
+#### Auto-generated Types (`uuid`, `timestamp`)
+
+```typescript
+const schema = defineSchema({
+  sessions: {
+    id: column.uuid().pk(), // Auto-generated UUID v4
+    idWithDefault: column.uuid().pk().default(uuid({ version: 'v6' })), // Replace auto-generated UUID v4
+    createdAt: column.timestamp(), // Auto-generated timestamp
+    defaultTs: column.timestamp().default(getTimestamp()), // Auto-generated timestamp with default using utility built-in function
+    customTs: column.timestamp().default(new Chronos().toLocalISOString() as Timestamp), // Default timestamp with custom format
+  },
+});
 ```
 
+> **Note:**
+>
+> - Auto-generated values can be overridden by providing explicit values during insert.
+> - Use the `default()` modifier to set custom default values instead of auto-generated ones.
+> - Auto-generated values are generated at runtime during insert operations.
+> - Type extensions for `uuid` and `timestamp` are not applicable since they are already typed.
+> - For custom UUID versions, use [`uuid`](https://toolbox.nazmul-nhb.dev/docs/utilities/hash/uuid) utility from [`nhb-toolbox`](https://www.npmjs.com/package/nhb-toolbox).
+> - For custom timestamp formats, use date libraries like [`Chronos`](https://toolbox.nazmul-nhb.dev/docs/classes/Chronos) (from [`nhb-toolbox`](https://www.npmjs.com/package/nhb-toolbox)) or [`date-fns`](https://www.npmjs.com/package/date-fns) to generate ISO 8601 strings.
+
 ##### Boolean Types (`bool`, `boolean`)
 
 ```typescript
@@ -688,6 +726,163 @@ await db
   .run();
 ```
 
+### Transactions
+
+Transactions enable you to perform multiple operations across multiple tables atomically. All operations in a transaction either succeed together or fail together, ensuring data consistency.
+
+#### Basic Transaction
+
+```typescript
+// Create a user and their first post atomically
+await db.transaction(['users', 'posts'], async (ctx) => {
+  const newUser = await ctx
+    .insert('users')
+    .values({ name: 'John Doe', email: 'john@example.com' })
+    .run();
+
+  await ctx
+    .insert('posts')
+    .values({
+      userId: newUser.id,
+      title: 'My First Post',
+      content: 'Hello World!',
+    })
+    .run();
+});
+```
+
+#### Transaction with Multiple Operations
+
+```typescript
+// Transfer data between tables atomically
+await db.transaction(['users', 'posts', 'comments'], async (ctx) => {
+  // Update user
+  await ctx
+    .update('users')
+    .set({ isActive: true })
+    .where((user) => user.id === 1)
+    .run();
+
+  // Create post
+  const post = await ctx
+    .insert('posts')
+    .values({ userId: 1, title: 'New Post', content: 'Content' })
+    .run();
+
+  // Add comment
+  await ctx
+    .insert('comments')
+    .values({ postId: post.id, userId: 1, text: 'First comment!' })
+    .run();
+
+  // Query within transaction
+  const userPosts = await ctx
+    .from('posts')
+    .where((p) => p.userId === 1)
+    .findAll();
+
+  console.log(`User now has ${userPosts.length} posts`);
+});
+```
+
+#### Automatic Rollback
+
+```typescript
+try {
+  await db.transaction(['users', 'posts'], async (ctx) => {
+    const user = await ctx
+      .insert('users')
+      .values({ name: 'Alice', email: 'alice@example.com' })
+      .run();
+
+    // This will cause the entire transaction to rollback
+    throw new Error('Something went wrong!');
+
+    // This never executes
+    await ctx
+      .insert('posts')
+      .values({ userId: user.id, title: 'Post' })
+      .run();
+  });
+} catch (error) {
+  console.error('Transaction failed:', error);
+  // No data was inserted - transaction was rolled back
+}
+```
+
+> **Note:**
+>
+> - Transactions guarantee atomicity: all operations succeed or all fail.
+> - If any operation fails or an error is thrown, the entire transaction is automatically rolled back.
+> - Transaction context (`ctx`) provides `insert()`, `update()`, `delete()`, and `from()` methods.
+> - All operations must be performed on tables specified in the transaction.
+
+### Export Database
+
+Export your database data as JSON for backup, migration, or debugging purposes. The export includes metadata and table data, and automatically triggers a browser download.
+
+#### Export All Tables
+
+```typescript
+// Export entire database with pretty-printed JSON
+await db.export();
+// Downloads: my-database-2026-02-04T10-30-45-123Z.json
+```
+
+#### Export Specific Tables
+
+```typescript
+// Export only users and posts tables
+await db.export({
+  tables: ['users', 'posts'],
+  filename: 'users-posts-backup.json',
+});
+```
+
+#### Export with Custom Options
+
+```typescript
+// Export with custom configuration
+await db.export({
+  tables: ['users'], // Optional: specific tables
+  filename: 'users-export.json', // Optional: custom filename
+  pretty: false, // Optional: compact JSON (default: true)
+  includeMetadata: true, // Optional: include metadata (default: true)
+});
+```
+
+#### Export Data Structure
+
+The exported JSON file contains:
+
+```json
+{
+  "metadata": {
+    "dbName": "my-database",
+    "version": 1,
+    "exportedAt": "2026-02-04T10:30:45.123Z",
+    "tables": ["users", "posts"]
+  },
+  "data": {
+    "users": [
+      { "id": 1, "name": "Alice", "email": "alice@example.com" },
+      { "id": 2, "name": "Bob", "email": "bob@example.com" }
+    ],
+    "posts": [
+      { "id": 1, "userId": 1, "title": "First Post", "content": "..." }
+    ]
+  }
+}
+```
+
+> **Note:**
+>
+> - Exported files are automatically downloaded in the browser.
+> - Default filename format: `{dbName}-{timestamp}.json`
+> - Metadata is included by default but can be disabled.
+> - Use `pretty: true` (default) for human-readable JSON.
+> - Use `pretty: false` for compact JSON (smaller file size).
+
 ---
 
 ## 📚 API Reference
@@ -827,6 +1022,105 @@ const allUsers = await db.from('users').findAll();
 console.log(allUsers);
 ```
 
+#### `transaction<Tables>(tables: Tables[], callback: TransactionCallback): Promise<void>`
+
+Executes multiple database operations across multiple tables in a single atomic transaction.
+
+**Parameters:**
+
+- `tables`: Array of table names to include in the transaction
+- `callback`: Async function that receives a transaction context and performs operations
+
+**Returns:** Promise that resolves when the transaction completes successfully
+
+**Transaction Context Methods:**
+
+- `ctx.insert(table)`: Insert records within the transaction
+- `ctx.update(table)`: Update records within the transaction
+- `ctx.delete(table)`: Delete records within the transaction
+- `ctx.from(table)`: Query records within the transaction
+
+**Example:**
+
+```typescript
+// Create user and post atomically
+await db.transaction(['users', 'posts'], async (ctx) => {
+  const user = await ctx
+    .insert('users')
+    .values({ name: 'Alice', email: 'alice@example.com' })
+    .run();
+
+  await ctx
+    .insert('posts')
+    .values({ userId: user.id, title: 'First Post', content: 'Hello!' })
+    .run();
+});
+```
+
+> **Important:**
+>
+> - All operations succeed or all fail (atomicity).
+> - If any operation fails or an error is thrown, the entire transaction is rolled back.
+> - Only tables specified in the `tables` array can be accessed within the transaction.
+> - Transactions use IndexedDB's native transaction mechanism.
+
+#### `export(options?: ExportOptions): Promise<void>`
+
+Exports database data as a JSON file and triggers a browser download.
+
+**Parameters:**
+
+- `options`: Optional export configuration
+  - `options.tables`: Array of table names to export (default: all tables)
+  - `options.filename`: Custom filename (default: `{dbName}-{timestamp}.json`)
+  - `options.pretty`: Enable pretty-printed JSON (default: `true`)
+  - `options.includeMetadata`: Include export metadata (default: `true`)
+
+**Returns:** Promise that resolves when the export completes
+
+**Example:**
+
+```typescript
+// Export all tables with default settings
+await db.export();
+
+// Export specific tables with custom filename
+await db.export({
+  tables: ['users', 'posts'],
+  filename: 'backup-2026-02-04.json',
+  pretty: true,
+});
+
+// Export without metadata in compact format
+await db.export({
+  pretty: false,
+  includeMetadata: false,
+});
+```
+
+**Exported JSON Structure:**
+
+```typescript
+{
+  metadata?: {  // Optional (when includeMetadata = true)
+    dbName: string;
+    version: number;
+    exportedAt: string;  // ISO 8601 timestamp
+    tables: string[];
+  };
+  data: {
+    [tableName: string]: Array<Record<string, any>>;
+  };
+}
+```
+
+> **Note:**
+>
+> - Automatically triggers a file download in the browser.
+> - Exported data includes all records from specified tables.
+> - Use for backup, debugging, or data migration.
+> - File download works in browser environments only.
+
 ---
 
 ### Schema Functions
@@ -1028,6 +1322,40 @@ const emailColumn = column.text().validate((val) => { /* ... */ });
 const validatorFn = emailColumn[ValidateFn]; // Function reference
 ```
 
+#### `onUpdate<T>(updater: (currentValue: T) => T): Column`
+
+Sets a function to auto-update the column value during update operations.
+
+```typescript
+const schema = defineSchema({
+  users: {
+    id: column.int().pk().auto(),
+    name: column.text(),
+    updatedAt: column.timestamp().onUpdate(() => getTimestamp()),
+  },
+});
+```
+
+> **Note:**
+>
+> - The updater function is called automatically during update operations.
+> - **Important**: It overrides any value provided during updates.
+> - It receives the current value of the column and should return the updated value.
+> - This is useful for fields like `"updatedAt"` timestamps that need to be refreshed on each update.
+> - If multiple updaters are chained, only the last one is used.
+> - Should not be used with auto-generated indexed columns like primary keys.
+> - The updated value is validated according to the column's type and custom validators (if any).
+
+**Access the `OnUpdate` symbol (advanced):**
+
+```typescript
+import { OnUpdate } from 'locality-idb';
+
+// Access updater function programmatically
+const updatedAtColumn = column.timestamp().onUpdate(() => getTimestamp());
+const updaterFn = updatedAtColumn[OnUpdate]; // Function reference
+```
+
 ---
 
 ### Query Methods
@@ -1329,6 +1657,86 @@ isTimestamp('invalid'); // false
 isTimestamp(123); // false
 ```
 
+#### `isUUID(value: unknown): value is UUID<UUIDVersion>`
+
+Checks if a value is a valid UUID string (v1, v4, or v5).
+
+**Parameters:**
+
+- `value`: The value to check
+
+**Returns:** `true` if the value is a valid UUID, otherwise `false`
+
+**Example:**
+
+```typescript
+import { isUUID } from 'locality-idb';
+
+// Valid UUIDs
+isUUID('d9428888-122b-11e8-b642-0ed5f89f718b'); // true (v1)
+isUUID('6ba7b810-9dad-11d1-80b4-00c04fd430c8'); // true (v1)
+isUUID('550e8400-e29b-41d4-a716-446655440000'); // true (v4)
+
+// Invalid formats
+isUUID('not-a-uuid');             // false
+isUUID('12345678-1234-1234-1234-123456789abc'); // false (invalid version)
+isUUID(123456789);                // false
+```
+
+#### `isEmail(value: unknown): value is EmailString`
+
+Checks if a value is a valid email string.
+
+**Parameters:**
+
+- `value`: The value to check
+
+**Returns:** `true` if the value is a valid email, otherwise `false`
+
+**Example:**
+
+```typescript
+import { isEmail } from 'locality-idb';
+
+// Valid emails
+isEmail('user@example.com');              // true
+isEmail('first.last@sub.domain.co.uk');   // true
+isEmail('user+filter@example.org');       // true
+
+// Invalid emails
+isEmail('plain-string');           // false
+isEmail('user@.com');             // false
+isEmail('@example.com');          // false
+isEmail('user@domain');           // false
+isEmail(12345);                   // false
+```
+
+#### `isURL(value: unknown): value is URLString`
+
+Checks if a value is a valid URL string.
+
+**Parameters:**
+
+- `value`: The value to check
+
+**Returns:** `true` if the value is a valid URL, otherwise `false`
+
+**Example:**
+
+```typescript
+import { isURL } from 'locality-idb';
+
+// Valid URLs
+isURL('https://example.com');       // true
+isURL('ftp://files.test/path?q=1'); // true
+
+// Invalid URLs
+isURL('example.com');             // false (missing protocol)
+isURL('http://');                 // false (empty domain)
+isURL('//cdn.domain/image.png');  // false (`URL` constructor cannot parse it)
+isURL(123456);                    // false
+```
+
 #### `openDBWithStores(name: string, stores: StoreConfig[], version?: number): Promise<IDBDatabase>`
 
 Opens an IndexedDB database with specified stores (low-level API).
@@ -1530,6 +1938,48 @@ type Selected = SelectFields<User, { name: true; email: true }>;
 // { name: string; email: string }
 ```
 
+### Transaction & Export Types
+
+```typescript
+import type {
+  TransactionContext,
+  TransactionCallback,
+  ExportOptions,
+  ExportData,
+} from 'locality-idb';
+
+// TransactionContext: Context object provided to transaction callback
+type TxContext = TransactionContext<Schema, TableName, ['users', 'posts']>;
+
+// TransactionCallback: Function signature for transaction operations
+type TxCallback = TransactionCallback<Schema, TableName, ['users']>;
+
+// ExportOptions: Configuration options for database export
+type ExportOpts = ExportOptions<'users' | 'posts'>;
+/*
+{
+  tables?: ('users' | 'posts')[];
+  filename?: string;
+  pretty?: boolean;
+  includeMetadata?: boolean;
+}
+*/
+
+// ExportData: Structure of exported database data
+type Exported = ExportData;
+/*
+{
+  metadata?: {
+    dbName: string;
+    version: number;
+    exportedAt: Timestamp;
+    tables: string[];
+  };
+  data: Record<string, GenericObject[]>;
+}
+*/
+```
+
 ---
 
 ## 📄 License