capitalsix-data-table 0.1.0

package/README.md

@@ -0,0 +1,253 @@
+# DataTable
+
+A lightweight, framework-agnostic in-memory data table with fully typed CRUD operations. Use it anywhere you need to manage a collection of objects: plain TypeScript, Node.js, React state handlers, Svelte stores, etc.
+
+## Features
+
+- **Typed rows** — generic over any object type `T`
+- **Insert** with optional duplicate-key guard
+- **Update** by predicate — via mutation function or replacement object
+- **Upsert** — insert new rows or update existing ones in a single call
+- **Delete** by predicate, returns deleted rows
+- **Sort** in-place with a custom comparator
+- **Query** all rows or filter with a predicate
+- **Bulk replace** via `setRows` for full re-initialisation
+- Zero runtime dependencies
+
+## Install
+
+```bash
+npm install capitalsix-data-table
+```
+
+## Quick Start
+
+```ts
+import { DataTable } from 'capitalsix-data-table';
+
+type User = { id: number; name: string; age: number };
+
+const table = new DataTable<User>([
+  { id: 1, name: 'Alice', age: 30 },
+  { id: 2, name: 'Bob',   age: 25 },
+]);
+
+const users = table.getRows();
+// [{ id: 1, name: 'Alice', age: 30 }, { id: 2, name: 'Bob', age: 25 }]
+```
+
+## API
+
+### `constructor(initialRows?: T[])`
+
+Creates a new table, optionally pre-populated with rows.
+
+```ts
+const empty  = new DataTable<User>();
+const seeded = new DataTable<User>([{ id: 1, name: 'Alice', age: 30 }]);
+```
+
+---
+
+### `getRows(predicate?: (row: T) => boolean): T[]`
+
+Returns all rows, or only the rows matching the predicate.
+
+```ts
+const all   = table.getRows();
+const young = table.getRows(u => u.age < 30);
+```
+
+---
+
+### `setRows(rows: T[]): void`
+
+Replaces **all** current rows with the provided array. Useful for bulk re-initialisation (e.g. after loading fresh data from an API).
+
+```ts
+table.setRows([
+  { id: 10, name: 'Carol', age: 28 },
+  { id: 11, name: 'Dave',  age: 35 },
+]);
+```
+
+---
+
+### `insertRows(rows: T[], primaryKey?: keyof T): void`
+
+Appends rows to the table. When `primaryKey` is provided, the method throws if any incoming key already exists, preventing accidental duplicates.
+
+```ts
+// Insert without key guard
+table.insertRows([{ id: 3, name: 'Eve', age: 22 }]);
+
+// Insert with duplicate-key guard
+table.insertRows([{ id: 4, name: 'Frank', age: 40 }], 'id');
+
+// Throws: "Duplicate primary key value found in existing rows for key: id"
+table.insertRows([{ id: 1, name: 'Alice again', age: 99 }], 'id');
+```
+
+---
+
+### `updateRows(predicate, update, primaryKey?): T[]`
+
+Updates all rows matching `predicate` and returns them (already reflecting the changes).
+
+**Mutation-function style** — receives each matched row and mutates it directly:
+
+```ts
+table.updateRows(
+  u => u.id === 1,
+  u => { u.age += 1; },
+);
+```
+
+**Replacement-object style** — merges the object onto each matched row while preserving the primary key:
+
+```ts
+table.updateRows(
+  u => u.id === 2,
+  { id: 0, name: 'Bob Updated', age: 26 },
+  'id',   // primaryKey is required; its value is preserved from the original row
+);
+```
+
+---
+
+### `upsertRows(rows: T[], primaryKey: keyof T): DataTableUpsertResult<T>`
+
+Inserts rows whose key does not yet exist; updates rows whose key already exists. Returns an object `{ inserted, updated }` so callers can react to each outcome.
+
+```ts
+const result = table.upsertRows(
+  [
+    { id: 1, name: 'Alice', age: 31 }, // key exists -> updated
+    { id: 5, name: 'Grace', age: 27 }, // new key   -> inserted
+  ],
+  'id',
+);
+
+console.log(result.updated.length);  // 1
+console.log(result.inserted.length); // 1
+```
+
+---
+
+### `deleteRows(predicate: (row: T) => boolean): T[]`
+
+Removes all rows that match the predicate and returns them.
+
+```ts
+const removed = table.deleteRows(u => u.age < 25);
+console.log(removed); // rows that were deleted
+```
+
+---
+
+### `sortRows(compareFn: (a: T, b: T) => number): void`
+
+Sorts rows in place using the provided comparator (same contract as `Array.prototype.sort`).
+
+```ts
+// Sort by age ascending
+table.sortRows((a, b) => a.age - b.age);
+
+// Sort by name alphabetically
+table.sortRows((a, b) => a.name.localeCompare(b.name));
+```
+
+---
+
+## Examples
+
+### Build a simple in-memory cache
+
+```ts
+import { DataTable } from 'capitalsix-data-table';
+
+type Product = { sku: string; name: string; stock: number };
+
+const cache = new DataTable<Product>();
+
+// Load initial catalogue
+cache.setRows(await fetchProducts());
+
+// Reduce stock for a purchased item
+cache.updateRows(
+  p => p.sku === 'ABC-123',
+  p => { p.stock -= 1; },
+);
+
+// Sync with latest server data, inserting new products and updating changed ones
+const { inserted, updated } = cache.upsertRows(await fetchProducts(), 'sku');
+console.log(`Synced: ${inserted.length} new, ${updated.length} updated`);
+```
+
+---
+
+### Filter and sort for display
+
+```ts
+const inStock = table.getRows(p => p.stock > 0);
+
+// Clone before sorting if you do not want to mutate the table order.
+// Use sortRows() when you *do* want the table itself sorted.
+const sorted = [...inStock].sort((a, b) => a.name.localeCompare(b.name));
+```
+
+---
+
+### Use inside a React reducer
+
+```ts
+import { DataTable } from 'capitalsix-data-table';
+
+type State = { table: DataTable<User> };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'UPSERT_USERS':
+      state.table.upsertRows(action.payload, 'id');
+      return { ...state }; // shallow clone to trigger re-render
+
+    case 'DELETE_USER':
+      state.table.deleteRows(u => u.id === action.id);
+      return { ...state };
+
+    default:
+      return state;
+  }
+}
+```
+
+---
+
+### Typed interfaces for dependency injection
+
+`DataTable` implements two interfaces you can use for narrowing in function signatures:
+
+```ts
+import type { IDataTable, IDataTableInitial } from 'capitalsix-data-table';
+
+// Read/write CRUD — no bulk replace
+function processUsers(table: IDataTable<User>) {
+  table.insertRows([{ id: 99, name: 'Test', age: 0 }], 'id');
+}
+
+// Bulk replace only — used during initialisation
+function loadUsers(table: IDataTableInitial<User>, users: User[]) {
+  table.setRows(users);
+}
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+npm run build
+```

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "capitalsix-data-table",
+  "version": "0.1.0",
+  "description": "A lightweight, framework-agnostic in-memory data table with typed CRUD operations: insert, update, upsert, delete, sort, and query rows.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "author": {
+    "name": "Mike Wijnen",
+    "email": "mike@capitalsix.nl",
+    "url": "https://capitalsix.nl"
+  },
+  "repository": {
+    "url": "https://github.com/capital-six/data-table"
+  },
+  "ignore": [
+    "src/",
+    "node_modules/",
+    "PUBLISH.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npmignore --auto"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.4.8",
+    "@testing-library/react": "^16.0.1",
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^5.0.0",
+    "jsdom": "^25.0.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.5",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "npmignore": "^0.3.5"
+  }
+}