JSON Repository

A TypeScript-based repository pattern implementation for managing JSON data files. This module provides a flexible way to create and manage repositories with different scopes: singleton, scoped, and transient.

Installation

To install the module, use pnpm:

pnpm add json-repository

Usage

Creating a Repository

You can create a repository using the createRepository function. This function allows you to specify the scope of the repository: singleton, scoped, or transient.

Example:

import { createRepository } from 'json-repository';

const repository = createRepository<MyEntity>('my-entity.json', process.cwd(), 'singleton');

Using the Repository

Once you have a repository instance, you can perform various operations such as fetching all data, adding new items, updating existing items, and deleting items.

Example:

async function performOperations() {
  const repository = createRepository<MyEntity>('my-entity.json', process.cwd(), 'scoped');

  // Fetch all items
  const items = await repository.getAll();

  // Add a new item
  await repository.add({ id: '1', name: 'New Item' });

  // Update an existing item
  await repository.update('1', { id: '1', name: 'Updated Item' });

  // Delete an item
  await repository.delete('1');
}

Using with Hooks

For React applications, you can use the useRepository utility function to integrate repositories with React hooks.

Example:

import { useRepository } from 'json-repository';

function MyComponent() {
  const repository = useRepository<MyEntity>('my-entity.json', 'singleton');

  // Use the repository for operations
}

Custom Hook Example

You can create a custom hook to manage repository data and integrate it with React components.

Custom Hook:

import { useRepository } from 'json-repository';
import { useEffect, useState } from 'react';

export function useCustomRepository<T>(fileName: string, scope: 'singleton' | 'scoped' | 'transient' = 'singleton') {
  const repository = useRepository<T>(fileName, scope);
  const [data, setData] = useState<T[]>([]);

  useEffect(() => {
    async function fetchData() {
      const allData = await repository.getAll();
      setData(allData);
    }
    fetchData();
  }, [repository]);

  return { data, repository };
}

Component Example:

import { useCustomRepository } from '../hooks/useCustomRepository';

interface Item {
  id: string;
  name: string;
}

export default function HomePage() {
  const { data, repository } = useCustomRepository<Item>('items.json');

  const addItem = async () => {
    const newItem: Item = { id: '3', name: 'New Item' };
    await repository.add(newItem);
    // Refresh data after adding
    const updatedData = await repository.getAll();
    setData(updatedData);
  };

  return (
    <div>
      <h1>Items</h1>
      <ul>
        {data.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
      <button onClick={addItem}>Add Item</button>
    </div>
  );
}

Scopes

• Singleton: A single instance is shared across the entire application.
• Scoped: A new instance is created for each request or operation, but it can be reused within that scope.
• Transient: A new instance is created every time it is requested.

Error Handling

The module includes basic error handling to log and throw errors when creating or using repositories. Ensure to handle these errors in your application logic as needed.