rads-db 3.2.27 → 3.2.30

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import { g as RadsConfig, T as TypeDefinition } from './types-33ba4f76.js';
+import { g as RadsConfig, T as TypeDefinition } from './types-3f6b8235.js';
 import 'mssql';
 import '_rads-db';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as EntityDecoratorArgs, U as UiDecoratorArgs, a as UiFieldDecoratorArgs, V as ValidateEntityDecoratorArgs, b as ValidateFieldDecoratorArgs, F as FieldDecoratorArgs, C as ComputedDecoratorArgs, S as Schema, D as DriverConstructor, c as Driver, d as ComputedContext, R as RadsRequestContext, e as CreateRadsDbArgs, f as CreateRadsDbClientArgs } from './types-33ba4f76.js';
-export { O as Change, x as ComputedContextGlobal, k as CreateRadsArgsDrivers, m as CreateRadsDbArgsNormalized, ak as DeepKeys, af as DeepPartial, ad as DeepPartialWithNulls, ae as DeepPartialWithNullsItem, al as EntityMethods, w as EnumDefinition, v as FieldDefinition, J as FileSystemNode, u as FileUploadArgs, q as FileUploadDriver, p as FileUploadResult, H as GenerateClientNormalizedOptions, B as GenerateClientOptions, a9 as Get, $ as GetAggArgs, a0 as GetAggArgsAgg, a3 as GetAggArgsAny, a6 as GetAggResponse, _ as GetArgs, a2 as GetArgsAny, a5 as GetArgsInclude, Q as GetManyArgs, a1 as GetManyArgsAny, a7 as GetManyResponse, a8 as GetResponse, aa as GetResponseInclude, ab as GetResponseIncludeSelect, ac as GetResponseNoInclude, s as GetRestRoutesArgs, G as GetRestRoutesOptions, t as GetRestRoutesResponse, ah as InverseRelation, aj as JsonPutOperations, M as MinimalDriver, ai as Put, P as PutEffect, g as RadsConfig, h as RadsConfigDataSource, r as RadsDbInstance, N as RadsFeature, y as RadsHookDoc, L as RadsUiSlotDefinition, K as RadsUiSlotName, I as RadsVitePluginOptions, ag as Relation, i as RequiredFields, l as RestDriverOptions, A as RestFileUploadDriverOptions, n as SchemaLoadResult, o as SchemaValidators, z as SqlDriverOptions, T as TypeDefinition, j as ValidateStringDecoratorArgs, X as VerifyManyArgs, a4 as VerifyManyArgsAny, Y as VerifyManyResponse, Z as Where, W as WhereJsonContains } from './types-33ba4f76.js';
+import { E as EntityDecoratorArgs, U as UiDecoratorArgs, a as UiFieldDecoratorArgs, V as ValidateEntityDecoratorArgs, b as ValidateFieldDecoratorArgs, F as FieldDecoratorArgs, C as ComputedDecoratorArgs, S as Schema, D as DriverConstructor, c as Driver, d as ComputedContext, R as RadsRequestContext, e as CreateRadsDbArgs, f as CreateRadsDbClientArgs } from './types-3f6b8235.js';
+export { O as Change, x as ComputedContextGlobal, k as CreateRadsArgsDrivers, m as CreateRadsDbArgsNormalized, ak as DeepKeys, af as DeepPartial, ad as DeepPartialWithNulls, ae as DeepPartialWithNullsItem, al as EntityMethods, w as EnumDefinition, v as FieldDefinition, J as FileSystemNode, u as FileUploadArgs, q as FileUploadDriver, p as FileUploadResult, H as GenerateClientNormalizedOptions, B as GenerateClientOptions, a9 as Get, $ as GetAggArgs, a0 as GetAggArgsAgg, a3 as GetAggArgsAny, a6 as GetAggResponse, _ as GetArgs, a2 as GetArgsAny, a5 as GetArgsInclude, Q as GetManyArgs, a1 as GetManyArgsAny, a7 as GetManyResponse, a8 as GetResponse, aa as GetResponseInclude, ab as GetResponseIncludeSelect, ac as GetResponseNoInclude, s as GetRestRoutesArgs, G as GetRestRoutesOptions, t as GetRestRoutesResponse, ah as InverseRelation, aj as JsonPutOperations, M as MinimalDriver, ai as Put, P as PutEffect, g as RadsConfig, h as RadsConfigDataSource, r as RadsDbInstance, N as RadsFeature, y as RadsHookDoc, L as RadsUiSlotDefinition, K as RadsUiSlotName, I as RadsVitePluginOptions, ag as Relation, i as RequiredFields, l as RestDriverOptions, A as RestFileUploadDriverOptions, n as SchemaLoadResult, o as SchemaValidators, z as SqlDriverOptions, T as TypeDefinition, j as ValidateStringDecoratorArgs, X as VerifyManyArgs, a4 as VerifyManyArgsAny, Y as VerifyManyResponse, Z as Where, W as WhereJsonContains } from './types-3f6b8235.js';
 import { RadsDb } from '_rads-db';
 export { RadsDb } from '_rads-db';
 import 'mssql';

package/dist/{types-33ba4f76.d.ts → types-3f6b8235.d.ts}

@@ -43,15 +43,20 @@ type GetArgsAny = GetArgs<any>;
 type GetAggArgsAny = GetAggArgs<any>;
 type VerifyManyArgsAny = VerifyManyArgs<any>;
 type RelationsAndNestedObjects<EN extends keyof EntityMeta> = EntityMeta[EN]['relations'] & EntityMeta[EN]['nestedObjects'];
+type JsonFieldsInclude<EN extends keyof EntityMeta> = [EntityMeta[EN]['jsonFields']] extends [never] ? unknown : {
+    [K in EntityMeta[EN]['jsonFields'] & string]?: {
+        _pick?: readonly string[];
+    };
+};
 type GetArgsInclude<EN extends keyof EntityMeta, R extends keyof RelationsAndNestedObjects<EN> = keyof RelationsAndNestedObjects<EN>> = [R] extends [never] ? {
-    _pick?: EntityMeta[EN]['primitives'][];
-} : {
-    _pick?: (EntityMeta[EN]['primitives'] | R)[];
+    _pick?: readonly (EntityMeta[EN]['primitives'] | EntityMeta[EN]['jsonFields'])[];
+} & JsonFieldsInclude<EN> : {
+    _pick?: readonly (EntityMeta[EN]['primitives'] | EntityMeta[EN]['jsonFields'] | R)[];
 } & {
     [K in R]?: GetArgsInclude<RelationsAndNestedObjects<EN>[K]['entityName']>;
-};
+} & JsonFieldsInclude<EN>;
 type GetAggResponse<EN extends keyof EntityMeta, A extends GetAggArgs<EN>> = {
-    [K in A['agg'][0]]: K extends '_count' ? number : number | undefined;
+    [K in A['agg'][number]]: K extends '_count' ? number : number | undefined;
 };
 interface GetManyResponse<EN extends keyof EntityMeta, A extends GetArgs<EN>> {
     nodes: GetResponse<EN, A>[];
@@ -70,14 +75,16 @@ type Get<EntityName extends keyof EntityMeta, Include extends keyof EntityMeta[E
 type RelationData<EN extends keyof EntityMeta, K extends keyof EntityMeta[EN]['relations']> = Pick<EntityMeta[EN]['relations'][K]['entity'], EntityMeta[EN]['relations'][K]['denormFields']>;
 type KeepArray<TMaybeArray, TType> = NonNullable<TMaybeArray> extends any[] ? TType[] : TType;
 type GetResponseInclude<EN extends keyof EntityMeta, I extends GetArgsInclude<EN>> = I extends {
-    _pick: string[];
+    _pick: readonly string[];
 } ? GetResponseIncludeSelect<EN, I> : {
     [K in keyof EntityMeta[EN]['type']]: K extends keyof EntityMeta[EN]['relations'] ? K extends keyof I ? KeepArray<EntityMeta[EN]['type'][K], GetResponseInclude<EntityMeta[EN]['relations'][K]['entityName'], I[K]>> : KeepArray<EntityMeta[EN]['type'][K], RelationData<EN, K>> : EntityMeta[EN]['type'][K];
 };
 type GetResponseIncludeSelect<EN extends keyof EntityMeta, I extends GetArgsInclude<EN>> = I extends {
-    _pick: (infer P)[];
+    _pick: readonly (infer P)[];
 } ? Pick<{
-    [K in keyof EntityMeta[EN]['type']]: K extends keyof EntityMeta[EN]['relations'] ? K extends keyof Omit<I, '_pick'> ? KeepArray<EntityMeta[EN]['type'][K], GetResponseInclude<EntityMeta[EN]['relations'][K]['entityName'], Omit<I, '_pick'>[K]>> : KeepArray<EntityMeta[EN]['type'][K], RelationData<EN, K>> : EntityMeta[EN]['type'][K];
+    [K in keyof EntityMeta[EN]['type']]: K extends keyof EntityMeta[EN]['relations'] ? K extends keyof Omit<I, '_pick'> ? KeepArray<EntityMeta[EN]['type'][K], GetResponseInclude<EntityMeta[EN]['relations'][K]['entityName'], Omit<I, '_pick'>[K]>> : KeepArray<EntityMeta[EN]['type'][K], RelationData<EN, K>> : K extends EntityMeta[EN]['jsonFields'] ? K extends keyof Omit<I, '_pick'> ? Omit<I, '_pick'>[K] extends {
+        _pick: (infer JP)[];
+    } ? Pick<NonNullable<EntityMeta[EN]['type'][K]>, JP & string> : EntityMeta[EN]['type'][K] : EntityMeta[EN]['type'][K] : EntityMeta[EN]['type'][K];
 }, ((P & string) | (Exclude<keyof I, '_pick'> & string)) & keyof EntityMeta[EN]['type']> : never;
 type GetResponseNoInclude<EN extends keyof EntityMeta> = {
     [K in keyof EntityMeta[EN]['type']]: K extends keyof EntityMeta[EN]['relations'] ? KeepArray<EntityMeta[EN]['type'][K], RelationData<EN, K>> : EntityMeta[EN]['type'][K];
@@ -119,14 +126,14 @@ interface EntityMethods<E, EN extends keyof EntityMeta> {
     /** Used to access underlying mechanism of storage directly.
      * Warning: bypasses all rads features - schema won't be validated, default values won't be filled, etc. */
     driver: Driver;
-    get<A extends GetArgs<EN>>(args: A, ctx?: RadsRequestContext): MaybePromise$1<GetResponse<EN, A>>;
-    getMany<A extends GetManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<GetManyResponse<EN, A>>;
-    getAgg<A extends GetAggArgs<EN>>(args: A, ctx?: RadsRequestContext): MaybePromise$1<GetAggResponse<EN, A>>;
-    getAll<A extends GetManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<GetManyResponse<EN, A>['nodes']>;
+    get<const A extends GetArgs<EN>>(args: A, ctx?: RadsRequestContext): MaybePromise$1<GetResponse<EN, A>>;
+    getMany<const A extends GetManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<GetManyResponse<EN, A>>;
+    getAgg<const A extends GetAggArgs<EN>>(args: A, ctx?: RadsRequestContext): MaybePromise$1<GetAggResponse<EN, A>>;
+    getAll<const A extends GetManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<GetManyResponse<EN, A>['nodes']>;
     put(data: Put<EN>, ctx?: RadsRequestContext): MaybePromise$1<GetResponseNoInclude<EN>>;
     putMany(data: Put<EN>[], ctx?: RadsRequestContext): MaybePromise$1<GetResponseNoInclude<EN>[]>;
-    verifyMany<A extends VerifyManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<VerifyManyResponse>;
-    verifyAll<A extends VerifyManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<Pick<VerifyManyResponse, 'correctCount' | 'incorrectCount'>>;
+    verifyMany<const A extends VerifyManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<VerifyManyResponse>;
+    verifyAll<const A extends VerifyManyArgs<EN>>(args?: A, ctx?: RadsRequestContext): MaybePromise$1<Pick<VerifyManyResponse, 'correctCount' | 'incorrectCount'>>;
 }
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...0[]];
 type Primitive = string | number | boolean | symbol | null | undefined;

package/drivers/memory.d.ts

@@ -1,5 +1,5 @@
-import type { Schema } from '@/types';
-import type { GetAggArgsAny, GetManyArgsAny } from '@/typesClientEngine';
+import type { MinimalDriver, Schema } from '../types';
+import type { GetAggArgsAny, GetManyArgsAny } from '../typesClientEngine';
 interface MemoryDriverOptions {
 }
 declare const _default: (options?: MemoryDriverOptions) => (schema: Schema, entity: string) => MinimalDriver;
@@ -7,6 +7,6 @@ export default _default;
 export declare function getAggFromArray(array: any[], args: GetAggArgsAny): Record<string, any>;
 export declare function queryArray(array: any[], args: GetManyArgsAny): {
     nodes: any;
-    cursor: any;
+    cursor: string | null;
 };
 export declare function getFilter(where: Record<string, any>, namePrefix?: string): ((x: any) => boolean | undefined) | null;

package/drivers/restApi.d.ts

@@ -1,3 +1,3 @@
-import type { RestDriverOptions, Schema } from '@/types';
+import type { MinimalDriver, RestDriverOptions, Schema } from '../types';
 declare const _default: (options?: RestDriverOptions) => (schema: Schema, entity: string) => MinimalDriver;
 export default _default;

package/drivers/sql.d.ts

@@ -1,4 +1,4 @@
-import type { SqlDriverOptions } from '@/types';
+import type { SqlDriverOptions } from '../types';
 import type { Schema } from 'rads-db';
 declare const _default: (options: SqlDriverOptions) => (schema: Schema, entity: string) => MinimalDriver;
 export default _default;

package/features/cache.d.ts

@@ -1,5 +1,14 @@
-import type { DriverConstructor } from '@/types';
-declare const _default: (options: CacheOptions) => RadsFeature;
+import type { DriverConstructor } from '../types';
+declare const _default: (options: CacheOptions) => {
+    name: string;
+    init(db: Record<string, any>, context: import("../types").ComputedContextGlobal): void;
+    beforeGet(args: import("../typesClientEngine").GetArgsAny, ctx: import("../types").RadsRequestContext, context: import("../types").ComputedContext): Promise<Record<string, any> | Record<string, any>[] | {
+        nodes: Record<string, any>[];
+        cursor: string | undefined;
+    } | undefined>;
+    afterGet(items: any[], args: import("../typesClientEngine").GetArgsAny, ctx: import("../types").RadsRequestContext, context: import("../types").ComputedContext): Promise<void>;
+    afterPut(items: import("../types").RadsHookDoc[], ctx: import("../types").RadsRequestContext, computedContext: import("../types").ComputedContext): Promise<void>;
+};
 export default _default;
 export interface EntityCacheOptions {
     driver?: DriverConstructor;

package/features/eventSourcing.d.ts

@@ -1,4 +1,4 @@
-import type { ComputedContext, RadsFeature, RadsRequestContext } from '@/types';
+import type { ComputedContext, RadsFeature, RadsRequestContext } from '../types';
 export interface EventSourcingFeatureOptions {
     applyEventIf?: (event: any, context: ComputedContext, ctx: RadsRequestContext) => boolean;
     freezeEvent?: (event: any, context: ComputedContext, ctx: RadsRequestContext) => boolean;

package/features/softDelete.d.ts

@@ -1,2 +1,5 @@
-declare const _default: () => RadsFeature;
+declare const _default: () => {
+    name: string;
+    beforeGet(args: import("../typesClientEngine").GetArgsAny, ctx: import("../types").RadsRequestContext, context: import("../types").ComputedContext): void;
+};
 export default _default;

package/fileUploadDrivers/azureStorageBlob.d.ts

@@ -1,4 +1,5 @@
 import type { StoragePipelineOptions } from '@azure/storage-blob';
+import type { FileUploadDriver } from '../types';
 interface AzureStorageBlobUploadDriverOptions {
     connectionString: string;
     defaultContainer?: string;

package/fileUploadDrivers/memory.d.ts

@@ -1,3 +1,4 @@
+import type { FileUploadDriver } from '../types';
 interface MemoryFileUploadDriverOptions {
 }
 declare const _default: (options?: MemoryFileUploadDriverOptions) => FileUploadDriver;

package/fileUploadDrivers/restApi.d.ts

@@ -1,3 +1,3 @@
-import type { RestFileUploadDriverOptions } from '@/types';
+import type { FileUploadDriver, RestFileUploadDriverOptions } from '../types';
 declare const _default: (options: RestFileUploadDriverOptions) => FileUploadDriver;
 export default _default;

package/fileUploadDrivers/supabaseStorage.d.ts

@@ -1,4 +1,5 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
+import type { FileUploadDriver } from '../types';
 declare const _default: (options: SupabaseFileUploadDriverOptions) => FileUploadDriver;
 export default _default;
 interface SupabaseFileUploadDriverOptions {

package/llms.txt

@@ -0,0 +1,409 @@
+# rads-db
+
+> TypeScript-first universal data access library. Define entities as decorated classes, get strongly-typed CRUD methods, filtering, pagination, JOINs across any storage backend. Works on both server and browser.
+
+## Setup
+
+```bash
+npm install rads-db
+```
+
+Create `rads.config.ts` at the project root:
+
+```typescript
+import { defineRadsConfig, schemaFromFiles } from 'rads-db/config'
+
+export default defineRadsConfig({
+  dataSources: {
+    db: {
+      schema: schemaFromFiles('./entities'), // folder with your entity classes
+    },
+  },
+})
+```
+
+Run codegen after every schema change (generates TypeScript types and metadata):
+
+```bash
+npx rads
+```
+
+Automate in `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "npx rads && <your-dev-command>",
+    "build": "npx rads && <your-build-command>"
+  }
+}
+```
+
+## Defining Entities
+
+Each entity is a TypeScript class in the entities folder. Use decorators from `rads-db`:
+
+```typescript
+import { entity, field, ui, validate, computed, precomputed, keepHistory } from 'rads-db'
+import type { Relation, InverseRelation } from 'rads-db'
+import type { TcRole } from './TcRole'
+import type { TcPost } from './TcPost'
+
+@entity()
+@ui<typeof TcUser>({ name: 'User', namePlural: 'Users', nameField: 'name', captionFields: ['id', 'name'], group: 'People' })
+export class TcUser {
+  id!: string
+
+  @validate<TcUser, any, string>({ preset: 'email' })
+  @ui({ name: 'Email Address', hint: 'Used for login' })
+  email!: string
+
+  name!: string
+  age?: number
+  isActive?: boolean
+  tags: string[] = []
+
+  // Relation: only { id } is stored; use include: { tcRole: {} } to load full object
+  tcRole!: Relation<TcRole>
+
+  // Relation with denormalized fields stored alongside the id
+  tcRoleWithName!: Relation<TcRole, 'name'>
+
+  // Computed inverse relation — not stored, derived at query time
+  tcPosts?: InverseRelation<'TcPost'>
+
+  @computed()
+  fullLabel?: string  // computed server-side, not stored
+
+  @precomputed({ preset: 'eventSourcing' })
+  status?: string     // precomputed and stored when source events change
+
+  @keepHistory()
+  statusHistory?: string  // keeps full history of changes
+}
+```
+
+### Decorator reference
+
+| Decorator | Target | Purpose |
+|-----------|--------|---------|
+| `@entity(args?)` | class | Marks class as a database entity; `args.driver` overrides default driver |
+| `@ui(args)` | class or field | Display hints for rads-ui (name, icon, captionFields, nameField, etc.) |
+| `@validate(args)` | class or field | Validation rules (presets, regex, min/maxLength, etc.) |
+| `@field(args?)` | field | Marks a relation field; `args.relation` points to the related class |
+| `@computed()` | field | Computed at query time, never stored |
+| `@precomputed()` | field | Computed and stored; recalculated when source data changes |
+| `@keepHistory()` | field | Stores full change history |
+
+### Relation types
+
+```typescript
+Relation<T>                   // stores { id } only
+Relation<T, 'field1'|'field2'> // stores { id, field1, field2 } (denormalized)
+InverseRelation<'EntityName'> // reverse lookup — computed, not stored
+```
+
+### Field validation presets (string)
+
+`text` | `html` | `markdown` | `alpha` | `alphanum` | `number` | `decimalNumber` | `email` | `icon` | `imageUrl` | `fileUrl` | `absoluteUrl` | `relativeUrl` | `phoneNumber` | `datetime` | `date` | `time` | `timeInterval` | `duration` | `hexColor`
+
+## Creating the DB instance
+
+```typescript
+import { createRadsDb } from 'rads-db'
+
+const db = createRadsDb('db')
+// db.tcUser, db.tcPost, db.tcRole, … — one property per entity (lowerFirst of class name)
+```
+
+## CRUD Methods
+
+Every entity exposes the same set of methods on `db.<entityHandle>`:
+
+### get — fetch one record
+
+```typescript
+const user = await db.tcUser.get({ where: { id: 'user1' } })
+// returns undefined if not found
+```
+
+### getAll — fetch all matching records
+
+```typescript
+const users = await db.tcUser.getAll({ where: { isActive: true } })
+// returns T[]
+```
+
+### getMany — paginated fetch
+
+```typescript
+const page = await db.tcUser.getMany({
+  where: { isActive: true },
+  maxItemCount: 20,
+  cursor: previousPage.cursor, // pass cursor from previous response for next page
+  orderByArray: ['name_asc', 'age_desc'],
+})
+// returns { nodes: T[], cursor: string | undefined }
+// cursor === undefined means no more pages
+```
+
+### getAgg — aggregate queries
+
+```typescript
+const agg = await db.tcUser.getAgg({
+  where: { isActive: true },
+  agg: ['_count', 'age_min', 'age_max', 'age_sum'],
+})
+// agg._count: number; agg.age_min: number | undefined; etc.
+```
+
+### put — create or update one record (upsert by id)
+
+```typescript
+const saved = await db.tcUser.put({ id: 'user1', name: 'Alice', tcRole: { id: 'role1' } })
+// returns the full saved record
+// missing optional fields stay unchanged; null erases the value
+```
+
+### putMany — batch upsert
+
+```typescript
+const saved = await db.tcUser.putMany([
+  { id: 'user1', name: 'Alice', tcRole: { id: 'role1' } },
+  { id: 'user2', name: 'Bob',   tcRole: { id: 'role1' } },
+])
+```
+
+### construct — create in-memory object with defaults + a new UUID
+
+```typescript
+const newUser = db.tcUser.construct({ name: 'Draft' })
+// newUser.id is a fresh UUID; defaults from field declarations are applied
+```
+
+## Where Filters
+
+Where clauses are fully typed. Every primitive field supports operators via suffix:
+
+```typescript
+await db.tcUser.getAll({
+  where: {
+    name: 'Alice',                    // exact match
+    name_startsWith: 'Al',
+    name_istartsWith: 'al',           // case-insensitive
+    name_contains: 'lic',
+    name_icontains: 'LIC',
+    name_endsWith: 'ice',
+    name_in: ['Alice', 'Bob'],
+    name_notIn: ['Charlie'],
+    age_gt: 18,
+    age_gte: 18,
+    age_lt: 65,
+    age_lte: 65,
+    isActive: true,
+
+    // Logical combinators
+    _and: [{ isActive: true }, { age_gte: 18 }],
+    _or:  [{ name: 'Alice' }, { name: 'Bob' }],
+    _not: { isActive: false },
+
+    // Nested object filter
+    tcRole: { id: 'role1' },
+  },
+})
+```
+
+## Include (JOINs)
+
+Load related entities inline. Works across different databases/drivers:
+
+```typescript
+const post = await db.tcPost.get({
+  where: { id: 'post1' },
+  include: {
+    tcUser: {},                    // load full TcUser object
+    tcUser: { tcRole: {} },        // nested: load tcUser and its tcRole
+    tcComments: { _pick: ['id', 'text'] }, // load only specific fields of relation
+  },
+})
+```
+
+## Field selection with `_pick`
+
+```typescript
+const users = await db.tcUser.getAll({
+  include: { _pick: ['id', 'name'] }, // return only id and name
+})
+```
+
+## TypeScript utility types
+
+```typescript
+import type { Get, Put } from 'rads-db'
+
+// Get — shape returned by read operations (all fields non-nullable)
+type UserView = Get<'TcUser'>
+// With relations and field selection:
+type UserWithRole = Get<'TcUser', { tcRole: {}; _pick: ['id', 'name'] }>
+
+// Put — shape accepted by write operations (all fields except id are optional; null erases a value)
+type UserWrite = Put<'TcUser'>
+```
+
+**Form state pattern** — use `Put` for editable state; `Get` is assignable to `Put`:
+
+```typescript
+const data = await db.tcUser.get({ where: { id } })
+const form: Put<'TcUser'> = { ...data }  // Get is assignable to Put ✓
+form.age = null                           // null = erase the field
+await db.tcUser.put(form)
+```
+
+## Context (second argument to every method)
+
+Pass `RadsRequestContext` as the second argument to control behaviour per-request:
+
+```typescript
+import type { RadsRequestContext } from 'rads-db'
+
+const ctx: RadsRequestContext = {
+  getUser: () => ({ id: 'user1', role: 'admin' }),
+  dryRun: true,         // no changes written; effects returned as logs
+  noCache: true,        // bypass caching layer
+  excludeFeatures: ['softDelete'], // skip specific features
+}
+
+const result = await db.tcUser.put(data, ctx)
+```
+
+## Features
+
+Features hook into the get/put pipeline. Pass them to `createRadsDb`:
+
+```typescript
+import { createRadsDb } from 'rads-db'
+import softDelete from 'rads-db/features/softDelete'
+import eventSourcing from 'rads-db/features/eventSourcing'
+import cache from 'rads-db/features/cache'
+
+const db = createRadsDb('db', {
+  features: [
+    softDelete(),
+    eventSourcing(),
+    cache(),
+  ],
+})
+```
+
+### Built-in features
+
+| Feature | Import | What it does |
+|---------|--------|-------------|
+| `softDelete` | `rads-db/features/softDelete` | Filters out records where `isDeleted: true` automatically |
+| `eventSourcing` | `rads-db/features/eventSourcing` | Rebuilds aggregate from event log; entity needs `@precomputed({ preset: 'eventSourcing' })` |
+| `cache` | `rads-db/features/cache` | Adds a caching layer; bypass with `ctx.noCache = true` |
+
+### Custom feature
+
+```typescript
+import type { RadsFeature } from 'rads-db'
+
+const auditLog = (): RadsFeature => ({
+  name: 'auditLog',
+  afterPut(items, ctx, computedContext) {
+    for (const { doc, oldDoc } of items) {
+      console.log('changed', computedContext.typeName, doc.id)
+    }
+  },
+})
+```
+
+## Drivers
+
+Configure per data-source in `rads.config.ts` or pass to `createRadsDb`:
+
+| Import | Storage |
+|--------|---------|
+| `rads-db/drivers/memory` | In-memory (default; great for tests) |
+| `rads-db/drivers/sql` | MSSQL / MySQL / PostgreSQL (via mssql / mysql2 / pg) |
+| `rads-db/drivers/azureCosmos` | Azure Cosmos DB |
+| `rads-db/drivers/azureStorageBlob` | Azure Blob Storage |
+| `rads-db/drivers/indexedDb` | Browser IndexedDB |
+| `rads-db/drivers/restApi` | REST API (used by `createRadsDbClient`) |
+
+```typescript
+import sql from 'rads-db/drivers/sql'
+
+const db = createRadsDb('db', {
+  driver: sql({
+    server: 'localhost',
+    database: 'mydb',
+    authentication: { type: 'default', options: { userName: 'sa', password: 'pass' } },
+  }),
+})
+```
+
+## Client-side usage (browser)
+
+```typescript
+import { createRadsDbClient } from 'rads-db'
+
+// Uses fetch to talk to the server REST API; same methods as server-side db
+const db = createRadsDbClient('db', { driver: { baseUrl: '/api' } })
+
+const users = await db.tcUser.getAll({ where: { isActive: true } })
+```
+
+## REST API / Server endpoints
+
+Expose all entities over HTTP using `getRestRoutes`:
+
+```typescript
+// h3 / Nitro (Nuxt)
+import { defineEventHandler, getMethod, readBody } from 'h3'
+import { createRadsDb } from 'rads-db'
+import { getRestRoutes } from 'rads-db/integrations/restEndpoints'
+
+const db = createRadsDb('db')
+const routes = getRestRoutes({ db, prefix: '/api/' })
+
+export default defineEventHandler(async event => {
+  const path = event.path.split('?')[0]
+  const method = getMethod(event)
+  const handler = routes[path]?.[method]
+  if (!handler) return
+  const body = method !== 'GET' ? await readBody(event) : undefined
+  return handler({ body, context: event, headers: {} })
+})
+```
+
+Generated routes per entity (e.g. `TcUser` → handle `tcUser`):
+
+| Path | Method | Description |
+|------|--------|-------------|
+| `/api/tcUser` | `POST` | `db.tcUser.get(body)` |
+| `/api/tcUser` | `PUT` | `db.tcUser.put(body.data)` |
+| `/api/tcUser/list` | `POST` | `db.tcUser.getMany(body)` |
+| `/api/tcUser/list` | `PUT` | `db.tcUser.putMany(body.data)` |
+| `/api/tcUser/agg` | `POST` | `db.tcUser.getAgg(body)` |
+
+## OpenAPI / Swagger
+
+```typescript
+import { getOpenApiSpec } from 'rads-db/integrations/getOpenApiSpec'
+
+const spec = getOpenApiSpec(
+  { db, prefix: '/api/' },
+  { title: 'My App API', version: '1.0.0' },
+)
+```
+
+## Utilities
+
+```typescript
+import { merge, diff, cleanEntity } from 'rads-db'
+
+merge(target, source)    // deep merge source into target
+diff(oldObj, newObj)     // returns changed fields only
+cleanEntity(entity)      // strips undefined/null fields
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rads-db",
-  "version": "3.2.27",
+  "version": "3.2.30",
   "description": "Say goodbye to boilerplate code and hello to efficient and elegant syntax.",
   "author": "",
   "license": "ISC",
@@ -48,7 +48,8 @@
     "drivers",
     "fileUploadDrivers",
     "integrations",
-    "features"
+    "features",
+    "llms.txt"
   ],
   "peerDependencies": {
     "@azure/cosmos": ">=3",