@decaf-ts/db-decorators 0.8.15 → 0.8.17

package/README.md

@@ -5,6 +5,14 @@ The db-decorators library provides a comprehensive set of TypeScript decorators
 
 > Release docs refreshed on 2025-11-26. See [workdocs/reports/RELEASE_NOTES.md](./workdocs/reports/RELEASE_NOTES.md) for ticket summaries.
 
+### Core Concepts
+
+*   **`Repository`**: An abstract base class that implements the repository pattern, providing a consistent interface for CRUD operations.
+*   **Operation Hooks**: The `Repository` class provides `Prefix` and `Suffix` methods for each CRUD operation, allowing you to execute custom logic before and after the main operation.
+*   **Operation Decorators**: Decorators like `@onCreate`, `@onUpdate`, `@onDelete`, and `@onRead` allow you to attach custom logic to specific repository operations.
+*   **`Context`**: A class for passing contextual information through the different layers of your application.
+*   **Database-related Decorators**: A set of decorators for handling common database tasks, such as defining primary keys (`@id`), generating values (`@generated`), hashing values (`@hash`), composing values from other properties (`@composed`), and managing version numbers (`@version`).
+
 ![Licence](https://img.shields.io/github/license/decaf-ts/db-decorators.svg?style=plastic)
 ![GitHub language count](https://img.shields.io/github/languages/count/decaf-ts/db-decorators?style=plastic)
 ![GitHub top language](https://img.shields.io/github/languages/top/decaf-ts/db-decorators?style=plastic)
@@ -68,569 +76,178 @@ The db-decorators library is a powerful TypeScript framework for database operat
 The library is designed to be extensible and adaptable to different database backends, providing a consistent API regardless of the underlying storage mechanism.
 
 
-### How to Use
+# How to Use
 
-- [Initial Setup](./workdocs/tutorials/For%20Developers.md#_initial-setup_)
-- [Installation](./workdocs/tutorials/For%20Developers.md#installation)
+This guide provides examples of how to use the main features of the `@decaf-ts/db-decorators` library.
 
-## DB-Decorators Examples
+## Repository
 
-### 1. Defining Models with Decorators
+The `Repository` class is an abstract base class that implements the repository pattern.
 
-#### Basic Model Definition
+### Creating a Repository
 
-Description: Create a User model with ID, name, email, and password fields. The ID is marked as required and readonly, the password is hashed, and the email is required.
+To create a repository, you need to extend the `Repository` class and implement the abstract CRUD methods.
 
 ```typescript
-import { Model } from "@decaf-ts/decorator-validation";
-import { id, hash, version, transient } from "@decaf-ts/db-decorators";
-import { required, minLength, email as emailValidator } from "@decaf-ts/decorator-validation";
+import { Repository, Model } from '@decaf-ts/db-decorators';
+import { model, id, required } from '@decaf-ts/decorator-validation';
 
+@model()
 class User extends Model {
   @id()
   id: string;
 
-  @required()
-  @minLength(3)
-  name: string;
-
-  @required()
-  @emailValidator()
-  email: string;
-
-  @required()
-  @minLength(8)
-  @hash()
-  password: string;
-
-  @version()
-  version: number;
-
-  @transient()
-  temporaryData: any;
-}
-```
-
-#### Composed Properties
-
-Description: Create a Product model with a SKU that is automatically composed from other properties.
-
-```typescript
-import { Model } from "@decaf-ts/decorator-validation";
-import { id, composed, composedFromKeys } from "@decaf-ts/db-decorators";
-import { required } from "@decaf-ts/decorator-validation";
-
-class Product extends Model {
-  @id()
-  id: string;
-
-  @required()
-  category: string;
-
   @required()
   name: string;
-
-  @required()
-  variant: string;
-
-  @composed(['category', 'name', 'variant'], '-')
-  sku: string;
-
-  @composedFromKeys(['category', 'name'], '_', true, 'PROD_', '_KEY')
-  productKey: string;
 }
-```
-
-### 2. Implementing Repositories
-
-#### Basic Repository Implementation
-
-Description: Create a repository for the User model that implements the required CRUD operations.
 
-```typescript
-import { Repository } from "@decaf-ts/db-decorators";
-import { User } from "./models/User";
-
-class UserRepository extends Repository<User> {
+class UserRepository extends Repository<User, any> {
   constructor() {
     super(User);
   }
 
-  async create(model: User, ...args: any[]): Promise<User> {
-    // Implementation for creating a user in the database
-    console.log(`Creating user: ${model.name}`);
-    // Assign an ID if not already present
-    if (!model.id) {
-      model.id = Date.now().toString();
-    }
+  async create(model: User): Promise<User> {
+    // Implementation for creating a user
     return model;
   }
 
-  async read(key: string | number, ...args: any[]): Promise<User> {
-    // Implementation for reading a user from the database
-    console.log(`Reading user with ID: ${key}`);
-    return new User({ id: key, name: "Example User", email: "user@example.com" });
+  async read(key: string): Promise<User> {
+    // Implementation for reading a user
+    return new User({ id: key, name: 'User' });
   }
 
-  async update(model: User, ...args: any[]): Promise<User> {
-    // Implementation for updating a user in the database
-    console.log(`Updating user: ${model.name}`);
+  async update(model: User): Promise<User> {
+    // Implementation for updating a user
     return model;
   }
 
-  async delete(key: string | number, ...args: any[]): Promise<User> {
-    // Implementation for deleting a user from the database
-    console.log(`Deleting user with ID: ${key}`);
-    const user = await this.read(key);
-    return user;
+  async delete(key: string): Promise<User> {
+    // Implementation for deleting a user
+    const model = await this.read(key);
+    return model;
   }
 }
 ```
 
-#### Using Bulk Operations
+### Operation Hooks
 
-Description: Implement bulk operations for efficient batch processing of multiple models.
+The `Repository` class provides `Prefix` and `Suffix` methods for each CRUD operation, allowing you to execute custom logic before and after the main operation.
 
 ```typescript
-import { Repository } from "@decaf-ts/db-decorators";
-import { Product } from "./models/Product";
+class UserRepository extends Repository<User, any> {
+  // ...
 
-class ProductRepository extends Repository<Product> {
-  constructor() {
-    super(Product);
+  protected async createPrefix(model: User, ...args: any[]): Promise<[User, ...any[], any]> {
+    console.log('Before creating user...');
+    return [model, ...args];
   }
 
-  // Implement required CRUD methods
-  async create(model: Product, ...args: any[]): Promise<Product> {
-    // Implementation
+  protected async createSuffix(model: User, context: any): Promise<User> {
+    console.log('After creating user...');
     return model;
   }
-
-  async read(key: string | number, ...args: any[]): Promise<Product> {
-    // Implementation
-    return new Product({ id: key });
-  }
-
-  async update(model: Product, ...args: any[]): Promise<Product> {
-    // Implementation
-    return model;
-  }
-
-  async delete(key: string | number, ...args: any[]): Promise<Product> {
-    // Implementation
-    return await this.read(key);
-  }
-
-  // Override bulk methods for optimized implementation
-  async createAll(models: Product[], ...args: any[]): Promise<Product[]> {
-    console.log(`Bulk creating ${models.length} products`);
-    // Custom implementation for bulk creation
-    return models.map(model => {
-      if (!model.id) {
-        model.id = Date.now().toString();
-      }
-      return model;
-    });
-  }
-
-  async readAll(keys: string[] | number[], ...args: any[]): Promise<Product[]> {
-    console.log(`Bulk reading ${keys.length} products`);
-    // Custom implementation for bulk reading
-    return keys.map(key => new Product({ id: key }));
-  }
 }
 ```
 
-### 3. Using Operation Hooks
-
-#### Property Transformation Hooks
+## Operation Decorators
 
-Description: Use operation hooks to transform property values during database operations.
+Decorators like `@onCreate`, `@onUpdate`, `@onDelete`, and `@onRead` allow you to attach custom logic to specific repository operations.
 
 ```typescript
-import { Model } from "@decaf-ts/decorator-validation";
-import { id, onCreate, onUpdate, onCreateUpdate } from "@decaf-ts/db-decorators";
-import { required } from "@decaf-ts/decorator-validation";
-
-// Handler function for setting creation timestamp
-function setCreationTimestamp(repo, context, data, key, model) {
-  model[key] = new Date().toISOString();
-}
-
-// Handler function for setting update timestamp
-function setUpdateTimestamp(repo, context, data, key, model) {
-  model[key] = new Date().toISOString();
-}
-
-// Handler function for normalizing email
-function normalizeEmail(repo, context, data, key, model) {
-  if (model[key]) {
-    model[key] = model[key].toLowerCase().trim();
-  }
-}
+import { onCreate, onUpdate } from '@decaf-ts/db-decorators';
 
-class User extends Model {
-  @id()
-  id: string;
-
-  @required()
-  name: string;
-
-  @required()
-  @onCreateUpdate(normalizeEmail)
-  email: string;
-
-  @onCreate(setCreationTimestamp)
-  createdAt: string;
+const logOnCreate = onCreate((context, data, key, model) => {
+  console.log(`Creating model: ${model.constructor.name}`);
+});
 
-  @onUpdate(setUpdateTimestamp)
-  updatedAt: string;
+@model()
+@logOnCreate
+class Product extends Model {
+  // ...
 }
 ```
 
-#### Post-Operation Hooks
+## Context
 
-Description: Use post-operation hooks to perform actions after database operations.
+The `Context` class is used for passing contextual information through the different layers of your application.
 
 ```typescript
-import { Model } from "@decaf-ts/decorator-validation";
-import { id, afterCreate, afterUpdate, afterDelete } from "@decaf-ts/db-decorators";
+import { Context } from '@decaf-ts/db-decorators';
 
-// Handler function for logging after creation
-function logCreation(repo, context, data, key, model) {
-  console.log(`User created: ${model.id} - ${model.name}`);
-}
-
-// Handler function for logging after update
-function logUpdate(repo, context, data, key, model) {
-  console.log(`User updated: ${model.id} - ${model.name}`);
-}
+const context = new Context();
+context.set('user', 'admin');
 
-// Handler function for logging after deletion
-function logDeletion(repo, context, data, key, model) {
-  console.log(`User deleted: ${model.id} - ${model.name}`);
-}
-
-class User extends Model {
-  @id()
-  id: string;
-
-  @required()
-  name: string;
-
-  @required()
-  email: string;
-
-  @afterCreate(logCreation)
-  @afterUpdate(logUpdate)
-  @afterDelete(logDeletion)
-  _log: any; // This property is just a placeholder for the decorators
-}
+// You can then pass the context to repository methods
+// userRepository.create(user, context);
 ```
 
-### 4. Working with Contexts
+## Additional Decorators
 
-#### Creating and Using Contexts
+### `@id`
 
-Description: Create and use contexts to manage operation state and configuration.
+Marks a property as the primary key.
 
 ```typescript
-import { Context, Repository } from "@decaf-ts/db-decorators";
-import { User } from "./models/User";
-
-class UserRepository extends Repository<User> {
-  constructor() {
-    super(User);
-  }
-
-  // Implement required CRUD methods
-  async create(model: User, ...args: any[]): Promise<User> {
-    // Implementation
-    return model;
-  }
-
-  async read(key: string | number, ...args: any[]): Promise<User> {
-    // Implementation
-    return new User({ id: key });
-  }
-
-  async update(model: User, ...args: any[]): Promise<User> {
-    // Implementation
-    return model;
-  }
-
-  async delete(key: string | number, ...args: any[]): Promise<User> {
-    // Implementation
-    return await this.read(key);
-  }
-
-  // Example of using context
-  async createWithAudit(model: User, userId: string): Promise<User> {
-    // Create a context with audit information
-    const context = new Context().accumulate({
-      auditUser: userId,
-      auditTimestamp: new Date(),
-      skipValidation: false
-    });
-
-    // Pass the context to the create method
-    return this.create(model, context);
-  }
+@model()
+class Product extends Model {
+  @id()
+  productId: string;
 }
-
-// Usage
-const userRepo = new UserRepository();
-const newUser = new User({ name: "John Doe", email: "john@example.com" });
-const createdUser = await userRepo.createWithAudit(newUser, "admin123");
-```
-
-#### Context Hierarchies
-
-Description: Create hierarchical contexts for complex operations.
-
-```typescript
-import { Context, OperationKeys } from "@decaf-ts/db-decorators";
-import { User } from "./models/User";
-
-// Create a parent context
-const parentContext = new Context().accumulate({
-  transactionId: "tx123",
-  batchOperation: true
-});
-
-// Create a child context for a specific operation
-const childContext = parentContext.child<User, Context<any>>(
-  OperationKeys.CREATE,
-  User
-).accumulate({
-  operationId: "op456",
-  validationLevel: "strict"
-});
-
-// Access values from the context hierarchy
-console.log(childContext.get("transactionId")); // "tx123" (inherited from parent)
-console.log(childContext.get("operationId")); // "op456" (from child)
 ```
 
-### 5. Performing CRUD Operations
+### `@generated`
 
-#### Basic CRUD Operations
-
-Description: Perform basic CRUD operations using a repository.
+Indicates that a property's value is generated by the database.
 
 ```typescript
-import { User } from "./models/User";
-import { UserRepository } from "./repositories/UserRepository";
-
-async function userCrudExample() {
-  const userRepo = new UserRepository();
-
-  // Create a new user
-  const newUser = new User({
-    name: "Alice Smith",
-    email: "alice@example.com",
-    password: "securePassword123"
-  });
-  const createdUser = await userRepo.create(newUser);
-  console.log("Created user:", createdUser);
-
-  // Read a user
-  const userId = createdUser.id;
-  const retrievedUser = await userRepo.read(userId);
-  console.log("Retrieved user:", retrievedUser);
-
-  // Update a user
-  retrievedUser.name = "Alice Johnson";
-  const updatedUser = await userRepo.update(retrievedUser);
-  console.log("Updated user:", updatedUser);
-
-  // Delete a user
-  const deletedUser = await userRepo.delete(userId);
-  console.log("Deleted user:", deletedUser);
+@model()
+class Order extends Model {
+  @id()
+  @generated()
+  orderId: number;
 }
 ```
 
-#### Bulk Operations
+### `@hash`
 
-Description: Perform bulk operations for efficient batch processing.
+Automatically hashes a property's value.
 
 ```typescript
-import { Product } from "./models/Product";
-import { ProductRepository } from "./repositories/ProductRepository";
-
-async function productBulkExample() {
-  const productRepo = new ProductRepository();
-
-  // Create multiple products
-  const products = [
-    new Product({ category: "Electronics", name: "Laptop", variant: "15-inch" }),
-    new Product({ category: "Electronics", name: "Laptop", variant: "13-inch" }),
-    new Product({ category: "Electronics", name: "Smartphone", variant: "Pro" })
-  ];
-  const createdProducts = await productRepo.createAll(products);
-  console.log("Created products:", createdProducts);
-
-  // Read multiple products
-  const productIds = createdProducts.map(p => p.id);
-  const retrievedProducts = await productRepo.readAll(productIds);
-  console.log("Retrieved products:", retrievedProducts);
-
-  // Update multiple products
-  const updatedProducts = retrievedProducts.map(p => {
-    p.name = p.name + " (Updated)";
-    return p;
-  });
-  const savedProducts = await productRepo.updateAll(updatedProducts);
-  console.log("Updated products:", savedProducts);
-
-  // Delete multiple products
-  const deletedProducts = await productRepo.deleteAll(productIds);
-  console.log("Deleted products:", deletedProducts);
+@model()
+class User extends Model {
+  @hash()
+  password!: string;
 }
 ```
 
-### 6. Validation
-
-#### Model Validation
+### `@composed`
 
-Description: Validate models during CRUD operations to ensure data integrity.
+Composes a property's value from other properties.
 
 ```typescript
-import { Model, ModelErrorDefinition } from "@decaf-ts/decorator-validation";
-import { id } from "@decaf-ts/db-decorators";
-import { required, minLength, maxLength, email, pattern } from "@decaf-ts/decorator-validation";
+@model()
+class Person extends Model {
+  @composed(['firstName', 'lastName'], ' ')
+  fullName: string;
 
-class User extends Model {
-  @id()
-  id: string;
-
-  @required()
-  @minLength(2)
-  @maxLength(50)
-  name: string;
-
-  @required()
-  @email()
-  emailAddress: string;
-
-  @required()
-  @minLength(8)
-  @pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/, 
-    "Password must contain at least one uppercase letter, one lowercase letter, one number, and one special character")
-  password: string;
-
-  // Manual validation example
-  hasErrors(): ModelErrorDefinition | undefined {
-    const errors = super.hasErrors();
-    
-    // Add custom validation logic
-    if (this.name && this.name.includes('admin') && !this.emailAddress.includes('admin')) {
-      if (!errors) {
-        return {
-          name: ["Admin users must have an admin email address"]
-        };
-      }
-      errors.name = errors.name || [];
-      errors.name.push("Admin users must have an admin email address");
-    }
-    
-    return errors;
-  }
-}
-
-// Usage in a repository
-class UserRepository extends Repository<User> {
-  // ... other methods
-  
-  async create(model: User, ...args: any[]): Promise<User> {
-    // The Repository class will automatically validate the model
-    // and throw a ValidationError if validation fails
-    
-    // Custom validation can also be performed
-    const errors = model.hasErrors();
-    if (errors) {
-      throw new ValidationError(errors.toString());
-    }
-    
-    // Proceed with creation if validation passes
-    return model;
-  }
+  firstName: string;
+  lastName: string;
 }
 ```
 
-### 7. Identity Management
-
-#### Working with Model IDs
+### `@version`
 
-Description: Use the identity module to work with model IDs.
+Automatically manages a version number for optimistic locking.
 
 ```typescript
-import { Model } from "@decaf-ts/decorator-validation";
-import { id } from "@decaf-ts/db-decorators";
-import { findPrimaryKey, findModelId } from "@decaf-ts/db-decorators";
-
-class Document extends Model {
-  @id()
-  documentId: string;
-  
-  title: string;
-  content: string;
-}
-
-// Create a document instance
-const doc = new Document({
-  documentId: "doc-123",
-  title: "Sample Document",
-  content: "This is a sample document."
-});
-
-// Find the primary key property
-const pkInfo = findPrimaryKey(doc);
-console.log("Primary key property:", pkInfo.id); // "documentId"
-console.log("Primary key metadata:", pkInfo.props);
-
-// Get the primary key value
-const docId = findModelId(doc);
-console.log("Document ID:", docId); // "doc-123"
-
-// Try to get ID from a model without an ID value
-const emptyDoc = new Document();
-try {
-  const id = findModelId(emptyDoc); // Will throw an error
-} catch (error) {
-  console.error("Error:", error.message);
+@model()
+class Account extends Model {
+  @version()
+  version: number;
 }
-
-// Get ID with returnEmpty option
-const emptyId = findModelId(emptyDoc, true); // Returns undefined instead of throwing
-console.log("Empty ID:", emptyId);
 ```
 
 
-
-
-
-## Coding Principles
-
-- group similar functionality in folders (analog to namespaces but without any namespace declaration)
-- one class per file;
-- one interface per file (unless interface is just used as a type);
-- group types as other interfaces in a types.ts file per folder;
-- group constants or enums in a constants.ts file per folder;
-- group decorators in a decorators.ts file per folder;
-- always import from the specific file, never from a folder or index file (exceptions for dependencies on other packages);
-- prefer the usage of established design patters where applicable:
-  - Singleton (can be an anti-pattern. use with care);
-  - factory;
-  - observer;
-  - strategy;
-  - builder;
-  - etc;
-
-## Release Documentation Hooks
-Stay aligned with the automated release pipeline by reviewing [Release Notes](./workdocs/reports/RELEASE_NOTES.md) and [Dependencies](./workdocs/reports/DEPENDENCIES.md) after trying these recipes (updated on 2025-11-26).
-
-
 ### Related
 
 [![decaf-ts](https://github-readme-stats.vercel.app/api/pin/?username=decaf-ts&repo=decaf-ts)](https://github.com/decaf-ts/decaf-ts)