@decaf-ts/core 0.5.20 → 0.5.22

package/README.md

@@ -1,8 +1,6 @@
-![Banner](./workdocs/assets/Banner.png)
+# Decaf TS — Core Package
 
-## Core Module
-
-The Decaf TypeScript Core Module is a comprehensive framework that provides a robust foundation for building TypeScript applications with data persistence capabilities. It offers a flexible model-repository architecture with support for various storage mechanisms, relationship management, querying capabilities, and reactive programming through the Observer pattern. The framework simplifies data handling with decorators for model definition, identity management, and persistence operations while maintaining type safety throughout.
+Decaf Core provides the foundational building blocks for the Decaf TypeScript ecosystem: strongly-typed models, repository pattern, pluggable persistence adapters, a composable query DSL, and pagination/observer utilities. With decorators and an injectable registry, it wires models to repositories and adapters so you can build data access that is framework-agnostic yet fully typed.
 
 
 ![Licence](https://img.shields.io/github/license/decaf-ts/core.svg?style=plastic)
@@ -26,666 +24,316 @@ The Decaf TypeScript Core Module is a comprehensive framework that provides a ro
 ![Node Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=Node&query=$.engines.node&colorB=blue)
 ![NPM Version](https://img.shields.io/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&label=NPM&query=$.engines.npm&colorB=purple)
 
-Documentation available [here](https://decaf-ts.github.io/core/)
-
-### Description
-
-The Decaf TypeScript Core Module is a sophisticated framework designed to streamline data persistence and model management in TypeScript applications. Building upon the foundation of `db-decorators`, `decorator-validation`, and `injectable-decorators`, it provides a comprehensive solution for working with data models across various storage mechanisms.
-
-#### Architecture Overview
-
-The framework is organized into several key modules:
-
-1. **Model System**: At the heart of the framework is the `BaseModel` class, which serves as the foundation for all domain models. It provides automatic timestamp tracking and integrates with the validation system. The model system supports:
-   - Property decorators for defining model attributes
-   - Relationship decorators (`@oneToOne`, `@oneToMany`, `@manyToOne`) for defining associations between models
-   - Table and column mapping through `@table` and `@column` decorators
-   - Indexing capabilities with the `@index` decorator
-
-2. **Identity Management**: The framework includes robust identity handling with:
-   - Primary key generation through the `@pk` decorator
-   - Sequence generation for automatic ID assignment
-   - Utilities for table name resolution and sequence naming
-
-3. **Repository Pattern**: The repository module provides a clean abstraction for data access operations:
-   - CRUD operations (create, read, update, delete)
-   - Transaction support
-   - Relationship management with cascade operations
-   - Custom repository implementations through decorators
-
-4. **Query System**: A flexible query builder allows for:
-   - Condition-based filtering
-   - Property selection
-   - Pagination
-   - Sorting and ordering
-   - Statement execution
-
-5. **Persistence Layer**: The adapter-based persistence system:
-   - Abstracts away storage implementation details
-   - Supports multiple storage backends
-   - Provides sequence management
-   - Implements the Observer pattern for reactive updates
-
-6. **RAM Implementation**: An in-memory implementation of the persistence layer for:
-   - Testing purposes
-   - Prototyping
-   - Caching
-
-#### Key Features
-
-- **Type Safety**: Leverages TypeScript's type system to provide compile-time checks
-- **Decorator-Based Configuration**: Uses decorators for clean, declarative model definitions
-- **Relationship Management**: Handles one-to-one, one-to-many, and many-to-one relationships with automatic cascading
-- **Flexible Storage**: Works with any storage mechanism through the adapter pattern
-- **Reactive Updates**: Implements the Observer pattern for reactive programming
-- **Dependency Injection**: Integrates with dependency injection for flexible component wiring
-- **Raw Access**: Provides direct access to the underlying storage when needed
-- **Automatic Timestamps**: Tracks creation and update times automatically
-
-The Core Module is designed to be extensible and developer-friendly, reducing boilerplate code while providing powerful features for data management in TypeScript applications.
-
-
-### How to Use
-
-- [Initial Setup](../../workdocs/tutorials/For%20Developers.md#_initial-setup_)
-- [Installation](../../workdocs/tutorials/For%20Developers.md#installation)
-
-## Table of Contents
-
-- [Model Definition](#model-definition)
-- [Identity Management](#identity-management)
-- [Relationships](#relationships)
-- [Repository Operations](#repository-operations)
-- [Querying](#querying)
-- [Persistence](#persistence)
-- [Observer Pattern](#observer-pattern)
-
-## Model Definition
-
-### Creating a Basic Model
-
-Define a domain model by extending the BaseModel class and using decorators to define properties.
-
-```typescript
-import { BaseModel, required, email, pk } from '@decaf-ts/core';
-
-class User extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  username!: string;
-
-  @email()
-  email!: string;
-
-  @required()
-  firstName!: string;
-
-  @required()
-  lastName!: string;
-
-  constructor(data?: Partial<User>) {
-    super(data);
-  }
-}
-
-// Create a new user
-const user = new User({
-  username: 'johndoe',
-  email: 'john.doe@example.com',
-  firstName: 'John',
-  lastName: 'Doe'
-});
-```
-
-### Customizing Table and Column Names
-
-Use the `@table` and `@column` decorators to customize database table and column names.
-
+Documentation [here](https://decaf-ts.github.io/injectable-decorators/), Test results [here](https://decaf-ts.github.io/injectable-decorators/workdocs/reports/html/test-report.html) and Coverage [here](https://decaf-ts.github.io/injectable-decorators/workdocs/reports/coverage/lcov-report/index.html)
+
+
+# Core Package — Detailed Description
+
+The Decaf Core package provides a cohesive set of primitives for building strongly-typed data-access layers in TypeScript. It centers around:
+
+- Models (from @decaf-ts/decorator-validation) enhanced with identity and persistence metadata
+- A Repository abstraction that encapsulates CRUD, querying, and observation
+- Adapters that bridge repositories to underlying storage (in-memory, HTTP, TypeORM, etc.)
+- A fluent Query DSL (Statement/Condition) with pagination
+- Lightweight dependency injection utilities to auto-resolve repositories
+
+Below is an overview of the main modules and their public APIs exposed by core.
+
+1) Repository module
+- Repository<M>
+  - Constructor: new Repository(adapter: Adapter, clazz: Constructor<M>, ...)
+  - CRUD: create, read, update, delete
+  - Bulk ops: createAll, readAll, updateAll, deleteAll
+  - Hooks: createPrefix/createSuffix, updateAllPrefix, readAllPrefix, deleteAllPrefix (internal orchestration helpers)
+  - Query: select(...selectors?), query(condition?, orderBy?, order?, limit?, skip?)
+  - Observation: observe(observer, filter?), unObserve(observer), updateObservers(...), refresh(...)
+  - Repository registry helpers:
+    - static for(config, ...args): Proxy factory for building repositories with specific adapter config
+    - static forModel(model, alias?, ...args): returns a Repository instance or repository constructor registered for the model
+    - static get(model, alias?): low-level retrieval of a registered repository constructor
+    - static register(model, repoCtor, alias?)
+    - static getMetadata/setMetadata/removeMetadata(model)
+    - static getSequenceOptions(model)
+    - static indexes(model): reads index definitions for model
+    - static relations(model)
+    - static table(model), static column(model, attribute)
+- Decorators (repository/decorators)
+  - repository(modelCtor, flavour?):
+    - As property decorator: injects the repository instance for the annotated model
+    - As class decorator: registers the annotated class as the repository for the model; integrates with Injectables
+- Injectables registry (repository/injectables)
+  - InjectablesRegistry extends InjectableRegistryImp
+  - get<T>(name | token | ctor, flavour?): resolves a registered injectable; if not registered, attempts to infer the model and construct or fetch the appropriate repository based on adapter flavour or metadata (falling back to current adapter)
+- Types/utilities (repository/types, repository/utils)
+  - IndexMetadata, OrderDirection, generateInjectableNameForRepository, and other helpers/constants
+
+2) Persistence module
+- Adapter<N = any, Q = any, R = any, Ctx = Context>
+  - Base bridge between repository and the back-end. Offers:
+    - initialize(...), flags(...), context(...)
+    - prepare(model, pk): model -> record mapping using model metadata
+    - revert(record, clazz, pk, id, transient?): record -> model mapping
+    - CRUD: create, createAll, read, readAll, update, updateAll, delete, deleteAll
+    - raw(rawInput): pass-through for back-end specific commands
+    - Observation: observe/unObserve, updateObservers, refresh
+    - Flavour/alias management: current(), get(flavour), setCurrent(flavour), alias(), models(flavour), flavourOf(model)
+    - Factory helpers: Statement(), Dispatch(), ObserverHandler(), Sequence(options)
+    - for(config, ...args): proxy-bound adapter for a given configuration
+- Dispatch: batching/dispatch helpers used by Adapter
+- Sequence: provides identity/sequence generation based on SequenceOptions (see interfaces)
+- ObserverHandler: internal observer list and filtering logic used by repositories/adapters
+- constants, errors, types: PersistenceKeys, EventIds, ObserverFilter, etc.
+
+3) Query module
+- Statement<M extends Model>
+  - Fluent DSL to build and execute queries via the configured Adapter
+  - Methods:
+    - select(...keys?), distinct(key), count(key), max(key), min(key)
+    - from(modelCtor), where(Condition), orderBy([key, OrderDirection]), groupBy(key)
+    - limit(n), offset(n), execute(), raw(input), paginate(size)
+- Condition<M extends Model>
+  - Composable condition tree with a builder API and logical combinators
+  - Methods:
+    - and(cond), or(cond), not(cond)
+    - attribute/attr(name): switch attribute under construction
+    - hasErrors(exceptions?): validation helper
+    - group(cond1, GroupOperator, cond2)
+    - builder(): ConditionBuilder
+  - ConditionBuilder methods: eq, dif, gt, lt, gte, lte, in, regexp, build
+- Paginator<M>
+  - Abstract pagination helper returned by Statement.paginate(size)
+  - Properties: current, total, count, size
+  - Methods: page(n?), next(), previous(); requires an Adapter-specific concrete implementation
+
+4) Interfaces module
+- Observable<T>, Observer<T>: basic observer pattern primitives
+- Executor, RawExecutor: contracts for query execution
+- Queriable: minimal interface for types that can return a Statement
+- Paginatable: marks types that can paginate
+- SequenceOptions and defaults: sequence/generator configuration presets
+
+5) Model & Identity modules
+- BaseModel and supporting types: base class all models extend from
+- identity/decorators and identity/utils: helpers to derive table names, etc.
+- model/decorators: e.g., @model and other persistence-related metadata (provided by @decaf-ts/decorator-validation and enriched here)
+
+6) RAM runtime (core/src/ram)
+- RamAdapter, RamRepository, RamStatement, RamPaginator (in-memory implementations used by tests and examples)
+- Useful for local testing and reference behavior of the core abstractions.
+
+Design intent
+- Provide a consistent, typed data access layer decoupled from any particular storage or framework
+- Allow adapters to plug into multiple backends while preserving a uniform repository and query API
+- Make querying expressive but type-safe through fluent builders and model metadata
+- Enable DI and decorators for ergonomic repository wiring and testing
+
+
+# How To Use — Core Package
+
+Below are practical, focused examples for the public APIs exposed by the Core package. Each example includes a short description and valid TypeScript code. Examples are inspired by and aligned with the unit tests under core/tests.
+
+Prerequisites used across examples:
+- Ensure your model builder is set for tests/dev scenarios: Model.setBuilder(Model.fromModel)
+- Use the RAM adapter for quick in-memory demos
 ```typescript
-import { BaseModel, required, table, column, pk } from '@decaf-ts/core';
-
-@table('app_users')
-class User extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  username!: string;
-
-  @required()
-  @column('user_email')
-  email!: string;
-
-  @column('first_name')
-  firstName!: string;
-
-  @column('last_name')
-  lastName!: string;
-
-  constructor(data?: Partial<User>) {
-    super(data);
-  }
-}
-```
-
-### Creating Indexes
-
-Use the `@index` decorator to create database indexes for better query performance.
-
-```typescript
-import { BaseModel, required, index, pk, OrderDirection } from '@decaf-ts/core';
-
-class Product extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  @index([OrderDirection.ASC])
-  name!: string;
-
-  @required()
-  @index([OrderDirection.ASC, OrderDirection.DSC])
-  price!: number;
-
-  @required()
-  category!: string;
-
-  constructor(data?: Partial<Product>) {
-    super(data);
-  }
-}
-```
-
-## Identity Management
-
-### Using Primary Keys with Automatic Sequence Generation
-
-The `@pk` decorator marks a property as the primary key and sets up automatic sequence generation.
-
-```typescript
-import { BaseModel, pk, required } from '@decaf-ts/core';
-
-class Order extends BaseModel {
-  @pk({ type: 'Number' })
-  id!: number;
-
-  @required()
-  customerId!: string;
-
-  @required()
-  totalAmount!: number;
-
-  constructor(data?: Partial<Order>) {
-    super(data);
-  }
-}
-
-// The id will be automatically generated when the order is saved
-const order = new Order({
-  customerId: 'cust123',
-  totalAmount: 99.99
-});
-```
-
-### Custom Sequence Options
-
-Customize the sequence generation for primary keys.
-
-```typescript
-import { BaseModel, pk, required } from '@decaf-ts/core';
-
-class Invoice extends BaseModel {
-  @pk({
-    type: 'BigInt',
-    name: 'invoice_sequence',
-    startWith: 1000,
-    incrementBy: 1
-  })
-  invoiceNumber!: bigint;
-
-  @required()
-  orderId!: number;
-
-  @required()
-  amount!: number;
-
-  constructor(data?: Partial<Invoice>) {
-    super(data);
-  }
-}
-```
-
-## Relationships
-
-### One-to-One Relationships
-
-Define a one-to-one relationship between models.
-
-```typescript
-import { BaseModel, pk, required, oneToOne } from '@decaf-ts/core';
-
-class User extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  username!: string;
-
-  @oneToOne(Profile)
-  profile?: Profile;
-
-  constructor(data?: Partial<User>) {
-    super(data);
-  }
-}
-
-class Profile extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  userId!: string;
-
-  bio?: string;
-
-  avatarUrl?: string;
-
-  constructor(data?: Partial<Profile>) {
-    super(data);
-  }
+import { Model, model } from "@decaf-ts/decorator-validation";
+import type { ModelArg } from "@decaf-ts/decorator-validation";
+import {
+  Adapter,
+  OrderDirection,
+  Paginator,
+  Repository,
+  repository,
+  uses,
+  pk,
+  column,
+  table,
+} from "@decaf-ts/core";
+import { RamAdapter, RamRepository } from "@decaf-ts/core/ram";
+
+@table("tst_user")
+@model()
+class User extends Model {
+  @pk() id!: string;
+  @column("tst_name") name!: string;
+  @column("tst_nif") nif!: string;
+  constructor(arg?: ModelArg<User>) { super(arg); }
 }
 ```
 
-### One-to-Many Relationships
-
-Define a one-to-many relationship between models.
 
+- Repository + RAM adapter: basic CRUD
+Description: Create a RamAdapter and a Repository for a model and perform CRUD operations; mirrors core/tests/unit/RamAdapter.test.ts and adapter.test.ts.
 ```typescript
-import { BaseModel, pk, required, oneToMany } from '@decaf-ts/core';
-
-class Author extends BaseModel {
-  @pk()
-  id!: string;
+import { NotFoundError } from "@decaf-ts/db-decorators";
 
-  @required()
-  name!: string;
+async function crudExample() {
+  const adapter = new RamAdapter();
+  const repo: RamRepository<User> = new Repository(adapter, User);
 
-  @oneToMany(Book)
-  books?: Book[];
-
-  constructor(data?: Partial<Author>) {
-    super(data);
-  }
-}
-
-class Book extends BaseModel {
-  @pk()
-  id!: string;
+  // CREATE
+  const created = await repo.create(
+    new User({ id: Date.now().toString(), name: "Alice", nif: "123456789" })
+  );
 
-  @required()
-  title!: string;
+  // READ
+  const read = await repo.read(created.id);
+  console.log(read.equals(created)); // true (same data, different instance)
 
-  @required()
-  authorId!: string;
+  // UPDATE
+  const updated = await repo.update(Object.assign(read, {name: "Alice 2" }));
 
-  constructor(data?: Partial<Book>) {
-    super(data);
-  }
+  // DELETE
+  const deleted = await repo.delete(created.id);
+  console.log(deleted.equals(updated)); // true
 }
 ```
 
-### Many-to-One Relationships
-
-Define a many-to-one relationship between models.
 
+- Adapter current and registered models; @repository class decorator
+Description: Show how to set/get current adapter and register a repository via the @repository decorator; mirrors adapter.test.ts.
 ```typescript
-import { BaseModel, pk, required, manyToOne } from '@decaf-ts/core';
-
-class Book extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  title!: string;
 
-  @required()
-  authorId!: string;
+@model()
+class Managed extends Model { constructor(arg?: ModelArg<Managed>) { super(arg); } }
 
-  @manyToOne(Author)
-  author?: Author;
-
-  constructor(data?: Partial<Book>) {
-    super(data);
-  }
+@repository(Managed)
+@uses("ram")
+class ManagedRepository extends Repository<Managed> {
+  // Concrete adapter-backed methods would be provided by adapter implementation
+  // For quick test or demo, use a RamAdapter
 }
 
-class Author extends BaseModel {
-  @pk()
-  id!: string;
+async function adapterRegistryExample() {
+  const adapter = new RamAdapter();
 
-  @required()
-  name!: string;
+  Adapter.setCurrent("ram"); // set current flavour
+  console.log(Adapter.current === Adapter.get("ram")); // true
 
-  constructor(data?: Partial<Author>) {
-    super(data);
-  }
+  // Models managed by current or specific adapter flavour
+  const managed = Adapter.models("ram");
+  console.log(Array.isArray(managed));
 }
 ```
 
-## Repository Operations
-
-### Basic CRUD Operations
-
-Perform basic CRUD operations using a repository.
+- Query building with select/order and execution
+Description: Build a statement with orderBy and run it, as done in core/tests/unit/Pagination.test.ts.
 
 ```typescript
-import { Repository, BaseModel, pk, required } from '@decaf-ts/core';
-
-class User extends BaseModel {
-  @pk({ type: 'Number' })
-  id!: string;
-
-  @required()
-  username!: string;
-
-  @required()
-  email!: string;
-
-  constructor(data?: Partial<User>) {
-    super(data);
-  }
-}
-
-// Create a repository for the User model
-const userRepository = new Repository(User);
-
-// Create a new user
-async function createUser() {
-  const user = new User({
-    username: 'johndoe',
-    email: 'john.doe@example.com'
-  });
-
-  const createdUser = await userRepository.create(user);
-  console.log('User created with ID:', createdUser.id);
-  return createdUser;
-}
-
-// Read a user by ID
-async function getUserById(id: string) {
-  const user = await userRepository.read(id);
-  console.log('User found:', user);
-  return user;
-}
+async function queryExample() {
+  const adapter = new RamAdapter();
+  const repo: RamRepository<User> = new Repository(adapter, User);
+
+  // Seed data
+  await repo.createAll(
+    Array.from({ length: 5 }).map((_, i) =>
+      new User({ id: (i + 1).toString(), name: `u${i + 1}`, nif: "123456789" })
+    )
+  );
 
-// Update a user
-async function updateUser(user: User) {
-  user.email = 'new.email@example.com';
-  const updatedUser = await userRepository.update(user);
-  console.log('User updated');
-  return updatedUser;
-}
+  const results = await repo
+    .select()
+    .orderBy(["id", OrderDirection.ASC])
+    .execute();
 
-// Delete a user
-async function deleteUser(user: User) {
-  await userRepository.delete(user);
-  console.log('User deleted');
+  console.log(results.map((u) => u.id)); // ["1","2","3","4","5"]
 }
 ```
 
-## Querying
-
-### Basic Queries
-
-Perform basic queries using conditions.
+- Pagination with Paginator
+Description: Paginate query results using Statement.paginate(size), then page through results; mirrors Pagination.test.ts.
 
 ```typescript
-import { Repository, BaseModel, pk, required, Condition } from '@decaf-ts/core';
-
-class Product extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  name!: string;
-
-  @required()
-  price!: number;
-
-  @required()
-  category!: string;
-
-  constructor(data?: Partial<Product>) {
-    super(data);
-  }
-}
-
-const productRepository = new Repository(Product);
-
-// Find products by category
-async function findProductsByCategory(category: string) {
-  const condition = Condition.eq('category', category);
-  const products = await productRepository.find(condition);
-  console.log(`Found ${products.length} products in category ${category}`);
-  return products;
-}
-
-// Find products with price greater than a value
-async function findExpensiveProducts(minPrice: number) {
-  const condition = Condition.gt('price', minPrice);
-  const products = await productRepository.find(condition);
-  console.log(`Found ${products.length} products with price > ${minPrice}`);
-  return products;
-}
-
-// Find products with complex conditions
-async function findSpecificProducts() {
-  const condition = Condition.and(
-    Condition.eq('category', 'electronics'),
-    Condition.or(
-      Condition.lt('price', 500),
-      Condition.gt('price', 1000)
+async function paginationExample() {
+  const adapter = new RamAdapter();
+  const repo: RamRepository<User> = new Repository(adapter, User);
+
+  // Seed data
+  const size = 25;
+  await repo.createAll(
+    Array.from({ length: size }).map((_, i) =>
+      new User({ id: (i + 1).toString(), name: `u${i + 1}`, nif: "123456789" })
     )
   );
-  const products = await productRepository.find(condition);
-  console.log(`Found ${products.length} specific products`);
-  return products;
-}
-```
-
-### Pagination
-
-Use pagination to handle large result sets.
-
-```typescript
-import { Repository, BaseModel, pk, required, OrderDirection } from '@decaf-ts/core';
-
-class Product extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  name!: string;
-
-  @required()
-  price!: number;
 
-  constructor(data?: Partial<Product>) {
-    super(data);
-  }
-}
-
-const productRepository = new Repository(Product);
+  const paginator: Paginator<User> = await repo
+    .select()
+    .orderBy(["id", OrderDirection.DSC])
+    .paginate(10);
 
-// Get paginated results
-async function getProductsPage(pageNumber: number, pageSize: number) {
-  const result = await productRepository.select()
-    .orderBy('name', OrderDirection.ASC)
-    .paginate(pageSize)
-    .page()
+  const page1 = await paginator.page(); // first page by default
+  const page2 = await paginator.next();
+  const page3 = await paginator.next();
 
-  console.log(`Page ${pageNumber}: ${result.length} products`);
-  console.log(`Total pages: ${result.totalPages}`);
-  console.log(`Total items: ${result.totalItems}`);
-
-  return result;
+  console.log(page1.length, page2.length, page3.length); // 10, 10, 5
 }
 ```
 
-### Property Selection
-
-Select specific properties from models.
 
+- Conditions: building filters
+Description: Compose conditions with the builder and apply them in a where clause.
 ```typescript
-import { Repository, BaseModel, pk, required } from '@decaf-ts/core';
-
-class User extends BaseModel {
-  @pk()
-  id!: string;
+import { Condition } from "@decaf-ts/core";
 
-  @required()
-  username!: string;
+async function conditionExample() {
+  const adapter = new RamAdapter();
+  const repo: RamRepository<User> = new Repository(adapter, User);
 
-  @required()
-  email!: string;
+  await repo.createAll([
+    new User({ id: "1", name: "Alice", nif: "111111111" }),
+    new User({ id: "2", name: "Bob", nif: "222222222" }),
+  ]);
 
-  @required()
-  password!: string;
-
-  constructor(data?: Partial<User>) {
-    super(data);
-  }
-}
-
-const userRepository = new Repository(User);
-
-// Select only specific properties
-async function getUsersPublicInfo() {
-  const users = await userRepository
-    .select(['id', 'username', 'email'])
-    .execute();
+  const cond = Condition.attr<User>("name")
+    .eq("Alice")
+    .build();
 
-  // The returned objects will only have id, username, and email properties
-  console.log('Users public info:', users);
-  return users;
+  const results = await repo.select().where(cond).execute();
+  console.log(results.length); // 1
 }
 ```
 
-## Persistence
 
-### Using Different Adapters
+- Adapter mapping: prepare and revert
+Description: Convert a model to a storage record and back using Adapter.prepare and Adapter.revert; mirrors adapter.test.ts.
+```typescript
+async function mappingExample() {
+  const adapter = new RamAdapter();
+  const repo: RamRepository<User> = new Repository(adapter, User);
 
-Configure and use different persistence adapters.
+  const toCreate = new User({ id: "abc", name: "Test", nif: "123456789" });
 
-```typescript
-import { 
-  Adapter, 
-  RamAdapter, 
-  Repository, 
-  BaseModel, 
-  pk, 
-  required 
-} from '@decaf-ts/core';
-
-class User extends BaseModel {
-  @pk()
-  id!: string;
-
-  @required()
-  username!: string;
-
-  constructor(data?: Partial<User>) {
-    super(data);
-  }
-}
+  // prepare: model -> record
+  const pk = "id"; // infer with findPrimaryKey(toCreate).id if available
+  const { record, id } = adapter.prepare(toCreate, pk);
+  console.log(id === toCreate.id); // true
 
-// Use RAM adapter for in-memory storage (useful for testing)
-const ramAdapter = new RamAdapter();
-const userRepository = new Repository(User, { adapter: ramAdapter });
-
-// Example with a hypothetical SQL adapter
-// const sqlAdapter = new SqlAdapter({
-//   host: 'localhost',
-//   port: 5432,
-//   database: 'myapp',
-//   username: 'user',
-//   password: 'password'
-// });
-// const userRepository = new Repository(User, { adapter: sqlAdapter });
-
-async function testRepository() {
-  // Create a user
-  const user = new User({ username: 'testuser' });
-  await userRepository.create(user);
-
-  // Read the user
-  const retrievedUser = await userRepository.read(user.id);
-  console.log('Retrieved user:', retrievedUser);
+  // revert: record -> model instance
+  const model = adapter.revert(record, User, pk, id) as User;
+  console.log(model instanceof User); // true
 }
 ```
 
-## Observer Pattern
-
-### Implementing an Observer
-
-Create an observer to react to changes in observable objects.
 
+- Auto-resolving repositories with InjectablesRegistry
+Description: Retrieve a repository by model name or constructor using the DI registry; see repository/injectables.ts flow.
 ```typescript
-import { Observer, Observable } from '@decaf-ts/core';
-
-// Create a custom observer
-class LoggingObserver implements Observer {
-  async refresh(...args: any[]): Promise<void> {
-    console.log('Observable was updated with args:', args);
-  }
-}
-
-// Example usage with a hypothetical observable repository
-class ObservableRepository implements Observable {
-  private observers: Observer[] = [];
-
-  observe(observer: Observer): void {
-    this.observers.push(observer);
-    console.log('Observer registered');
+import { Injectables } from "@decaf-ts/injectable-decorators";
+import { InjectablesRegistry } from "@decaf-ts/core";
+
+async function injectablesExample() {
+  // Register current adapter so repositories can be created
+  new RamAdapter();
+  Adapter.setCurrent("ram");
+
+  // Resolve by constructor
+  const userRepo = Injectables.get<Repository<User>>(User);
+  if (userRepo) {
+    const u = await userRepo.create(
+      new User({ id: "1", name: "A", nif: "123456789" })
+    );
+    console.log(!!u);
   }
-
-  unObserve(observer: Observer): void {
-    this.observers = this.observers.filter(obs => obs !== observer);
-    console.log('Observer unregistered');
-  }
-
-  async updateObservers(...args: any[]): Promise<void> {
-    console.log('Notifying observers...');
-    for (const observer of this.observers) {
-      await observer.refresh(...args);
-    }
-  }
-
-  // Example method that triggers an update
-  async performAction(action: string): Promise<void> {
-    console.log(`Performing action: ${action}`);
-    await this.updateObservers(action, new Date());
-  }
-}
-
-// Usage
-async function demonstrateObserverPattern() {
-  const repository = new ObservableRepository();
-  const logger = new LoggingObserver();
-
-  // Register the observer
-  repository.observe(logger);
-
-  // Perform an action that will notify the observer
-  await repository.performAction('save');
-
-  // Unregister the observer
-  repository.unObserve(logger);
-
-  // This action won't be logged by the observer
-  await repository.performAction('delete');
 }
 ```
 
@@ -729,6 +377,6 @@ So if you can, if this project in any way. either by learning something or simpl
 
 ## License
 
-This project is released under the [MIT License](./LICENSE.md).
+This project is released under the [AGPL-3.0-or-later License](./LICENSE.md).
 
 By developers, for developers...