@di-framework/di-framework-repo 0.0.0-prerelease-0

package/README.md

@@ -0,0 +1,128 @@
+# @geoffsee/df-repo
+
+A coherent abstraction of repositories and storage adapters for TypeScript, with optional integration for `di-framework`.
+
+## Features
+
+- **Storage Agnostic**: Decouples your business logic from the underlying storage technology (SQL, NoSQL, In-Memory, etc.).
+- **Standardized Patterns**: Provides `BaseRepository`, `EntityRepository`, and `SoftDeleteRepository` to handle common data access patterns.
+- **Built-in Pagination**: Standardized `Page` and `PaginatedResult` types with built-in support in adapters and repositories.
+- **In-Memory Implementation**: Includes a fully functional `InMemoryRepository` for prototyping and testing.
+- **DI Integration**: Seamlessly integrates with `di-framework` via the `@Repository` decorator.
+
+## Installation
+
+```bash
+bun add @geoffsee/df-repo
+```
+
+Required for DI integration: If you want to use the `@Repository` decorator for dependency injection, install the DI framework peer dependency.
+
+```bash
+bun add @di-framework/di-framework
+```
+
+Important: Always import from the scoped package name `@di-framework/di-framework/*`.
+
+Mixing different import IDs (e.g., `di-framework/*` or relative paths to sources) can load a second copy of the library and create a second global container instance.
+
+Correct:
+
+```ts
+import { useContainer } from "@di-framework/di-framework/container";
+import { Container, Component } from "@di-framework/di-framework/decorators";
+```
+
+Avoid:
+
+```ts
+import { useContainer } from "di-framework/container"; // Wrong: unscoped id
+import { Container } from "../../di-framework/decorators"; // Wrong: relative id
+```
+
+## Basic Usage
+
+### 1. Define your Entity
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+```
+
+### 2. Implement a Repository
+
+You can extend `InMemoryRepository` for quick prototyping:
+
+```typescript
+import { InMemoryRepository } from "@geoffsee/df-repo";
+
+class UserRepository extends InMemoryRepository<User, number> {
+  async findByEmail(email: string): Promise<User | null> {
+    const all = await this.findAll();
+    return all.find((u) => u.email === email) || null;
+  }
+}
+```
+
+### 3. Use with di-framework
+
+Use the `@Repository` decorator to automatically register your repository with the `di-framework` container.
+
+```typescript
+import { Repository } from "@geoffsee/df-repo";
+
+@Repository()
+class UserRepository extends InMemoryRepository<User, number> {
+  // ...
+}
+
+// In another service
+@Container()
+class UserService {
+  constructor(@Component(UserRepository) private users: UserRepository) {}
+
+  async listUsers() {
+    return this.users.findAll();
+  }
+}
+```
+
+## Storage Adapters
+
+The `StorageAdapter` interface allows you to implement custom backends.
+
+```typescript
+import { StorageAdapter, BaseRepository } from "@geoffsee/df-repo";
+
+class MyCustomAdapter<E, ID> implements StorageAdapter<E, ID> {
+  // Implement findById, save, delete, findPaginated, etc.
+}
+
+class MyRepository extends BaseRepository<User, number> {
+  constructor(adapter: MyCustomAdapter<User, number>) {
+    super(adapter);
+  }
+}
+```
+
+## API Overview
+
+### Repository Classes
+
+- `BaseRepository<E, ID>`: The foundational repository class.
+- `EntityRepository<E, ID>`: Standard entity-aware repository.
+- `SoftDeleteRepository<E, ID>`: Repository with soft-delete capabilities.
+- `InMemoryRepository<E, ID>`: Ready-to-use in-memory implementation.
+
+### Decorators
+
+- `@Repository(options)`: Registers the class as a singleton in `di-framework`.
+
+### Types
+
+- `StorageAdapter<E, ID>`: Interface for storage implementations.
+- `Page<T>` / `PaginatedResult<T>`: Standardized pagination metadata.
+- `EntityId`: Type alias for `string | number`.

package/dist/adapter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Minimal protocol that every storage backend must implement.
+ * Keeps repository layer agnostic to the underlying technology.
+ */
+export interface StorageAdapter<E, ID = string | number> {
+    /**
+     * Retrieve one entity by ID
+     */
+    findById(id: ID): Promise<E | null>;
+    /**
+     * Retrieve multiple entities by IDs
+     */
+    findMany(ids: ID[]): Promise<E[]>;
+    /**
+     * Retrieve all entities (use with care – pagination usually preferred)
+     */
+    findAll(): Promise<E[]>;
+    /**
+     * Create or update (most implementations do upsert under the hood)
+     */
+    save(entity: E): Promise<E>;
+    /**
+     * Delete by ID – returns whether deletion actually occurred
+     */
+    delete(id: ID): Promise<boolean>;
+    /**
+     * Optional: count matching records (used for pagination metadata)
+     */
+    count(filter?: Record<string, any>): Promise<number>;
+    /**
+     * Optional: exists check (cheaper than findById in many backends)
+     */
+    exists(id: ID): Promise<boolean>;
+    /**
+     * Paginated listing with basic filtering/sorting support
+     * Filter/sort format is deliberately loose – concrete adapters interpret it.
+     */
+    findPaginated(params: {
+        page?: number;
+        size?: number;
+        sort?: string | string[];
+        filter?: Record<string, any>;
+        withDeleted?: boolean;
+    }): Promise<{
+        items: E[];
+        total: number;
+        page: number;
+        size: number;
+        pages: number;
+    }>;
+    /**
+     * Optional – transaction support
+     * Return value of fn is returned from the transaction
+     */
+    transaction<T>(fn: (adapter: this) => Promise<T>): Promise<T>;
+    /**
+     * Optional – clean up / disconnect (important for tests, lambda, etc.)
+     */
+    dispose?(): Promise<void> | void;
+}
+/**
+ * Factory signature – allows dynamic creation of adapters
+ */
+export type StorageAdapterFactory<E, ID = string | number> = (config: unknown, // connection string, options, credentials, etc.
+entityName?: string) => Promise<StorageAdapter<E, ID>> | StorageAdapter<E, ID>;
+/**
+ * Helper type to extract Entity & ID from an adapter
+ */
+export type EntityOfAdapter<A> = A extends StorageAdapter<infer E, any> ? E : never;
+export type IdOfAdapter<A> = A extends StorageAdapter<any, infer ID> ? ID : never;

package/dist/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/decorators.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Repository decorator.
+ *
+ * This package requires `@di-framework/di-framework` as a peer dependency and
+ * delegates to its `@Container` decorator to register repositories with the
+ * same singleton/global container instance. Ensure you always import the DI
+ * framework using the scoped package name (`@di-framework/di-framework/*`) to
+ * avoid loading multiple copies and accidentally creating multiple containers.
+ */
+export declare function Repository(options?: {
+    singleton?: boolean;
+    container?: any;
+}): <T extends {
+    new (...args: any[]): {};
+}>(constructor: T) => T;

package/dist/decorators.js

@@ -0,0 +1,13 @@
+import { Container as ContainerDecorator } from "@di-framework/di-framework/decorators";
+/**
+ * Repository decorator.
+ *
+ * This package requires `@di-framework/di-framework` as a peer dependency and
+ * delegates to its `@Container` decorator to register repositories with the
+ * same singleton/global container instance. Ensure you always import the DI
+ * framework using the scoped package name (`@di-framework/di-framework/*`) to
+ * avoid loading multiple copies and accidentally creating multiple containers.
+ */
+export function Repository(options = {}) {
+    return ContainerDecorator(options);
+}

package/dist/in-memory.d.ts

@@ -0,0 +1,19 @@
+import { EntityRepository } from "./repository";
+import type { EntityId, PaginatedResult } from "./types";
+export declare class InMemoryRepository<E extends {
+    id: ID;
+}, ID extends string | number = EntityId> extends EntityRepository<E, ID> {
+    protected items: Map<ID, E>;
+    constructor();
+    findById(id: ID): Promise<E | null>;
+    findAll(): Promise<E[]>;
+    findMany(ids: ID[]): Promise<E[]>;
+    save(entity: E): Promise<E>;
+    delete(id: ID): Promise<boolean>;
+    upsert(entity: E): Promise<E>;
+    findPaginated(params: {
+        page?: number;
+        size?: number;
+        [p: string]: unknown;
+    }): Promise<PaginatedResult<E>>;
+}

package/dist/in-memory.js

@@ -0,0 +1,47 @@
+import { EntityRepository } from "./repository";
+export class InMemoryRepository extends EntityRepository {
+    items = new Map();
+    constructor() {
+        super(undefined);
+    }
+    async findById(id) {
+        return this.items.get(this.normalizeId(id)) || null;
+    }
+    async findAll() {
+        return Array.from(this.items.values());
+    }
+    async findMany(ids) {
+        return ids
+            .map((id) => this.items.get(this.normalizeId(id)))
+            .filter((e) => !!e);
+    }
+    async save(entity) {
+        this.items.set(this.normalizeId(entity.id), entity);
+        return entity;
+    }
+    async delete(id) {
+        return this.items.delete(this.normalizeId(id));
+    }
+    async upsert(entity) {
+        return this.save(entity);
+    }
+    async findPaginated(params) {
+        const page = params.page || 1;
+        const size = params.size || 10;
+        const all = await this.findAll();
+        // Filter out other params (simple exact match for this in-memory implementation)
+        const filters = Object.entries(params).filter(([key]) => key !== "page" && key !== "size");
+        const filtered = all.filter((item) => {
+            return filters.every(([key, value]) => item[key] === value);
+        });
+        const start = (page - 1) * size;
+        const items = filtered.slice(start, start + size);
+        return {
+            items,
+            total: filtered.length,
+            page,
+            size,
+            pages: Math.ceil(filtered.length / size),
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./adapter";
+export * from "./repository";
+export * from "./in-memory";
+export * from "./decorators";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./adapter";
+export * from "./repository";
+export * from "./in-memory";
+export * from "./decorators";

package/dist/repository.d.ts

@@ -0,0 +1,50 @@
+import type { StorageAdapter } from "./adapter";
+import type { EntityId, PaginatedResult } from "./types";
+export declare abstract class BaseRepository<E, ID = EntityId> {
+    protected readonly adapter: StorageAdapter<E, ID>;
+    protected constructor(adapter: StorageAdapter<E, ID>);
+    protected normalizeId(id: ID): ID;
+    findById(id: ID): Promise<E | null>;
+    findAll(): Promise<E[]>;
+    findMany(ids: ID[]): Promise<E[]>;
+    save(entity: E): Promise<E>;
+    delete(id: ID): Promise<boolean>;
+    findPaginated(params: {
+        page?: number;
+        size?: number;
+        [key: string]: unknown;
+    }): Promise<PaginatedResult<E>>;
+    protected inTransaction<T>(fn: () => Promise<T>): Promise<T>;
+    dispose(): Promise<void>;
+}
+export type Database<T extends Record<string, typeof BaseRepository>> = {
+    [K in keyof T]: T[K] extends new (...args: any[]) => infer R ? R : T[K] extends {
+        prototype: infer P;
+    } ? P : never;
+};
+export type RepositoryMap<T> = {
+    [K in keyof T]: T[K] extends BaseRepository<infer E> ? BaseRepository<E> : never;
+};
+export declare abstract class EntityRepository<E, ID = EntityId> extends BaseRepository<E, ID> {
+}
+export type EntityOf<R> = R extends BaseRepository<infer E> ? E : never;
+export type IdOf<R> = R extends BaseRepository<any, infer ID> ? ID : never;
+export interface SoftDeletable {
+    deletedAt: Date | null;
+}
+export declare abstract class SoftDeleteRepository<E extends SoftDeletable & {
+    id: ID;
+}, ID = EntityId> extends EntityRepository<E, ID> {
+    abstract softDelete(id: ID): Promise<boolean>;
+    abstract restore(id: ID): Promise<boolean>;
+    abstract findActive(): Promise<E[]>;
+    abstract findDeleted(): Promise<E[]>;
+    protected abstract afterNotifyDelete(id: ID): void;
+    softDeleteAndNotify(id: ID): Promise<boolean>;
+}
+export interface SearchableRepository<E, ID = EntityId> {
+    search(query: string, params?: {
+        page?: number;
+        size?: number;
+    }): Promise<PaginatedResult<E>>;
+}

package/dist/repository.js

@@ -0,0 +1,51 @@
+export class BaseRepository {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    normalizeId(id) {
+        // Default normalization (stringify) – can be overridden by subclasses if needed
+        return typeof id === "string" ? id : String(id);
+    }
+    // Forward most calls directly (you can add caching, validation, events here)
+    async findById(id) {
+        return this.adapter.findById(this.normalizeId(id));
+    }
+    async findAll() {
+        return this.adapter.findAll();
+    }
+    async findMany(ids) {
+        return this.adapter.findMany(ids.map((id) => this.normalizeId(id)));
+    }
+    async save(entity) {
+        return this.adapter.save(entity);
+    }
+    async delete(id) {
+        return this.adapter.delete(this.normalizeId(id));
+    }
+    async findPaginated(params) {
+        return this.adapter.findPaginated(params);
+    }
+    // Transaction support (if adapter provides it)
+    async inTransaction(fn) {
+        if (typeof this.adapter.transaction === "function") {
+            return this.adapter.transaction(() => fn());
+        }
+        return fn(); // fallback
+    }
+    async dispose() {
+        if (typeof this.adapter.dispose === "function") {
+            await this.adapter.dispose();
+        }
+    }
+}
+export class EntityRepository extends BaseRepository {
+}
+export class SoftDeleteRepository extends EntityRepository {
+    async softDeleteAndNotify(id) {
+        const ok = await this.softDelete(id);
+        if (ok)
+            this.afterNotifyDelete(id);
+        return ok;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export type EntityId = string | number;
+export interface Page<T> {
+    items: T[];
+    total: number;
+    page: number;
+    size: number;
+    pages: number;
+}
+export type PaginatedResult<T> = Page<T>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@di-framework/di-framework-repo",
+  "version": "0.0.0-prerelease-0",
+  "description": "A coherent abstraction of repositories and storage adapters for di-framework.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "@di-framework/di-framework": "2.0.4",
+    "typescript": "^5"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}