@rljson/io 0.0.63 → 0.0.65

package/dist/src/example.ts

@@ -4,7 +4,252 @@
 // Use of this source code is governed by terms that can be
 // found in the LICENSE file in the root of this package.
 
+import { TableCfg } from '@rljson/rljson';
+
+import { IoMem } from './io-mem.ts';
+import { IoMulti } from './io-multi.ts';
+
+
 // Run »pnpm updateGoldens« when you change this file
-export const example = async () => {};
 
+/**
+ * Example 1: Basic IoMem usage
+ */
+export const basicExample = async () => {
+  // Create and initialize in-memory database
+  const io = new IoMem();
+  await io.init();
+
+  // Create a table with schema
+  await io.createOrExtendTable({
+    tableCfg: {
+      key: 'users',
+      type: 'components',
+      columns: [
+        { key: '_hash', type: 'string', titleShort: 'Hash', titleLong: 'Hash' },
+        {
+          key: 'id',
+          type: 'number',
+          titleShort: 'ID',
+          titleLong: 'User ID',
+        },
+        {
+          key: 'name',
+          type: 'string',
+          titleShort: 'Name',
+          titleLong: 'User Name',
+        },
+        {
+          key: 'email',
+          type: 'string',
+          titleShort: 'Email',
+          titleLong: 'Email Address',
+        },
+      ],
+      isHead: false,
+      isRoot: false,
+      isShared: true,
+    },
+  });
+
+  // Write data
+  await io.write({
+    data: {
+      users: {
+        _type: 'components',
+        _data: [
+          { id: 1, name: 'Alice', email: 'alice@example.com' },
+          { id: 2, name: 'Bob', email: 'bob@example.com' },
+        ],
+      },
+    },
+  });
+
+  // Query data
+  const result = await io.readRows({
+    table: 'users',
+    where: { id: 1 },
+  });
+
+  console.log('Query result:', result);
+
+  // Get row count
+  const count = await io.rowCount('users');
+  console.log('Total users:', count);
+
+  // Dump entire database
+  const allData = await io.dump();
+  console.log('Database dump:', allData);
+
+  await io.close();
+};
+
+/**
+ * Example 2: Schema management
+ */
+export const schemaExample = async () => {
+  const io = new IoMem();
+  await io.init();
+
+  // Create a table with schema
+  await io.createOrExtendTable({
+    tableCfg: {
+      key: 'products',
+      type: 'components',
+      columns: [
+        { key: '_hash', type: 'string', titleShort: 'Hash', titleLong: 'Hash' },
+        {
+          key: 'sku',
+          type: 'string',
+          titleShort: 'SKU',
+          titleLong: 'Stock Keeping Unit',
+        },
+        {
+          key: 'name',
+          type: 'string',
+          titleShort: 'Name',
+          titleLong: 'Product Name',
+        },
+        {
+          key: 'price',
+          type: 'number',
+          titleShort: 'Price',
+          titleLong: 'Price in USD',
+        },
+        {
+          key: 'inStock',
+          type: 'boolean',
+          titleShort: 'In Stock',
+          titleLong: 'Available in Stock',
+        },
+      ],
+      isHead: false,
+      isRoot: false,
+      isShared: true,
+    },
+  });
+
+  // Check if table exists
+  const exists = await io.tableExists('products');
+  console.log('Table exists:', exists);
+
+  // Get table configuration
+  const configs = await io.rawTableCfgs();
+  console.log('Table configs:', configs);
+
+  await io.close();
+};
+
+/**
+ * Example 3: IoMulti with caching
+ */
+export const multiExample = async () => {
+  // Create cache layer
+  const cache = new IoMem();
+  await cache.init();
+
+  // Create "remote" layer (simulated with another IoMem)
+  const remote = new IoMem();
+  await remote.init();
+
+  // Create table schema in both
+  const tableCfg: TableCfg = {
+    key: 'items',
+    type: 'components',
+    columns: [
+      { key: '_hash', type: 'string', titleShort: 'Hash', titleLong: 'Hash' },
+      { key: 'id', type: 'number', titleShort: 'ID', titleLong: 'Item ID' },
+      {
+        key: 'value',
+        type: 'string',
+        titleShort: 'Value',
+        titleLong: 'Item Value',
+      },
+    ],
+    isHead: false,
+    isRoot: false,
+    isShared: true,
+  };
+
+  await cache.createOrExtendTable({ tableCfg });
+  await remote.createOrExtendTable({ tableCfg });
+
+  // Pre-populate remote with data
+  await remote.write({
+    data: {
+      items: {
+        _type: 'components',
+        _data: [
+          { id: 1, value: 'Remote Data' },
+          { id: 2, value: 'More Data' },
+        ],
+      },
+    },
+  });
+
+  // Create multi-tier Io
+  const io = new IoMulti([
+    {
+      io: cache,
+      priority: 1, // Check cache first
+      read: true,
+      write: true, // Write to cache
+      dump: false,
+    },
+    {
+      io: remote,
+      priority: 2, // Fallback to remote
+      read: true,
+      write: true, // Also persist to remote
+      dump: true, // Remote is source of truth
+    },
+  ]);
+
+  await io.init();
+
+  // First read hits remote, caches result
+  console.log('First read (hits remote):');
+  const data1 = await io.readRows({
+    table: 'items',
+    where: { id: 1 },
+  });
+  console.log(data1);
+
+  // Second read hits cache (faster!)
+  console.log('Second read (hits cache):');
+  const data2 = await io.readRows({
+    table: 'items',
+    where: { id: 1 },
+  });
+  console.log(data2);
+
+  // Write goes to both cache and remote
+  await io.write({
+    data: {
+      items: {
+        _type: 'components',
+        _data: [{ id: 3, value: 'New Data' }],
+      },
+    },
+  });
+
+  /* v8 ignore next -- @preserve */
+  await io.close();
+};
+
+/**
+ * Run all examples
+ */
+export const example = async () => {
+  console.log('=== Basic Example ===');
+  await basicExample();
+
+  console.log('\n=== Schema Example ===');
+  await schemaExample();
+
+  console.log('\n=== Multi-tier Example ===');
+  await multiExample();
+};
+
+// Uncomment to run examples
 // example();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/io",
-  "version": "0.0.63",
+  "version": "0.0.65",
   "description": "Low level interface for reading and writing RLJSON data",
   "homepage": "https://github.com/rljson/io",
   "bugs": "https://github.com/rljson/io/issues",
@@ -20,31 +20,31 @@
   ],
   "type": "module",
   "devDependencies": {
-    "@types/node": "^25.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.50.1",
-    "@typescript-eslint/parser": "^8.50.1",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "cross-env": "^10.1.0",
     "eslint": "^9.39.2",
-    "eslint-plugin-jsdoc": "^61.5.0",
+    "eslint-plugin-jsdoc": "^62.5.0",
     "eslint-plugin-tsdoc": "^0.5.0",
-    "globals": "^16.5.0",
+    "globals": "^17.2.0",
     "jsdoc": "^4.0.5",
     "read-pkg": "^10.0.0",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.50.1",
-    "vite": "^7.3.0",
-    "vite-node": "^5.2.0",
+    "typescript-eslint": "^8.54.0",
+    "vite": "^7.3.1",
+    "vite-node": "^5.3.0",
     "vite-plugin-dts": "^4.5.4",
-    "vite-tsconfig-paths": "^6.0.3",
-    "vitest": "^4.0.16",
+    "vite-tsconfig-paths": "^6.0.5",
+    "vitest": "^4.0.18",
     "vitest-dom": "^0.1.1"
   },
   "dependencies": {
-    "@rljson/hash": "^0.0.17",
+    "@rljson/hash": "^0.0.18",
     "@rljson/is-ready": "^0.0.17",
     "@rljson/json": "^0.0.23",
-    "@rljson/rljson": "^0.0.73",
+    "@rljson/rljson": "^0.0.75",
     "@rljson/validate": "^0.0.11"
   },
   "scripts": {