db-json Wiki

1. Introduction

@cut0x/db-json est une mini base JSON pour Node.js. Le module stocke des objets dans un seul fichier JSON, sans dépendance externe.

• Simple à utiliser
• CRUD complet
• Recherche par objet ou prédicat
• Zéro dépendance npm

2. Installation

npm install @cut0x/db-json

3. Démarrage rapide

const { createDb } = require("@cut0x/db-json");

const db = createDb({ file: "./users.json" });

db.insert({ id: 1, username: "alice", role: "admin" });
db.insert({ id: 2, username: "bob", role: "user" });

console.log(db.all());
console.log(db.getById(1));

4. Configuration

createDb(options) accepte:

• file (string, défaut data.json): chemin du fichier
• idKey (string, défaut id): clé unique
• pretty (number, défaut 2): indentation JSON
• createIfMissing (boolean, défaut true): création auto du fichier

5. API complète

• all(): retourne tous les enregistrements
• find(query): filtre (objet ou fonction)
• getById(id): objet ou null
• insert(entry): insertion avec id unique
• upsert(entry): insère ou remplace selon l'id
• updateById(id, patch): patch partiel, renvoie objet ou null
• replaceById(id, entry): remplacement complet
• removeById(id): true ou false
• clear(): supprime tout

6. Gestion des erreurs

Le module lève des erreurs explicites si:

• configuration invalide
• JSON invalide ou non tableau
• insertion sans id
• id déjà existant dans insert
• tentative de modifier la clé id dans updateById

try {
  db.insert({ username: "missing-id" });
} catch (error) {
  console.error(error.message);
}

7. TypeScript

Le package inclut index.d.ts.

import { createDb } from "@cut0x/db-json";

type User = { id: number; username: string; age: number };

const db = createDb<User>({ file: "./users.json" });
const one = db.getById(1);

8. Tests

npm test

9. FAQ

Le fichier JSON est créé automatiquement ?

Oui, si createIfMissing est à true (par défaut).

Puis-je changer la clé primaire ?

Oui, avec idKey (exemple: uuid).