Tuple Database

Common errors

• Argument of type 'string[]' is not assignable to parameter of type 'Tuple'.

  cause Attempting to use a simple array of strings instead of a properly structured tuple key (e.g., `['type', {id: '...'}]`) in `get`, `set`, `remove`, or `scan` operations.
  fix Ensure your tuple keys strictly conform to the `Schema` type definitions, using object literals for named parts of the tuple key (e.g., `['user', {id: userId}]`).

• TypeError: require is not a function

  cause Attempting to import `tuple-database` using CommonJS `require()` syntax in a project configured for ESM (e.g., in a modern Node.js environment with `"type": "module"` in `package.json` or within a browser module).
  fix Use ES module `import` statements: `import { Symbol } from 'tuple-database';`. Configure your project's build system (Webpack, Rollup, Vite) or Node.js environment to handle ESM correctly.

• Property 'key' does not exist on type '{ key: any; value: any; }'.

  cause This error typically occurs when trying to access properties of a `scan` or `get` result without proper TypeScript type narrowing, especially when the result could be `undefined` or `null`.
  fix Always check if the result of a database operation is `null` or `undefined` before accessing its properties. Use optional chaining (`?.`) or type guards to ensure type safety, e.g., `if (result) { console.log(result.key); }`.

Warnings

• gotcha Tuple Database is schemaless in its storage layer; schemas are enforced solely by application-level TypeScript types. Inconsistencies can easily arise if the TypeScript schema (`Schema` type) does not accurately reflect how tuples are actually written or read, leading to runtime data retrieval issues or type mismatches.
  Fix: Rigorously define and maintain your `Schema` TypeScript type. Use generic type parameters with `TupleDatabaseClient` and `transactionalReadWrite` to leverage TypeScript's type checking for all database operations.
• breaking Major version updates (e.g., from v1 to v2) may introduce breaking changes in API surface or internal tuple key structures. While not frequent, always consult the release notes for migration guides.
  Fix: Review the official changelog and migration guides for each major version upgrade. Update your tuple key definitions and API calls according to the new specifications.
• gotcha The `useTupleDatabase` React hook requires the `TupleDatabaseClient` instance to be passed as a prop, as it does not rely on React Context for database access. This differs from many other state management libraries.
  Fix: Ensure the `TupleDatabaseClient` instance is explicitly passed as a prop to any React component that uses `useTupleDatabase`. For top-level components, this means providing it from your application's root.

Install

• npm install tuple-database npm
• yarn add tuple-database yarn
• pnpm add tuple-database pnpm

Imports

• TupleDatabaseClient
  wrong:

  const TupleDatabaseClient = require('tuple-database').TupleDatabaseClient

  correct:

  import { TupleDatabaseClient } from 'tuple-database'

  The library primarily uses ESM imports; CommonJS `require` might lead to issues in modern environments or bundling.
• transactionalReadWrite
  wrong:

  import transactionalReadWrite from 'tuple-database'

  correct:

  import { transactionalReadWrite } from 'tuple-database'

  This is a named export, not a default export. Ensure curly braces are used.
• useTupleDatabase
  wrong:

  import { useTupleDatabase } from 'tuple-database'

  correct:

  import { useTupleDatabase } from 'tuple-database/useTupleDatabase'

  The React hook `useTupleDatabase` is exported from a specific subpath, not the main package entry point.

Quickstart

This quickstart demonstrates defining a schema, initializing an in-memory database, performing transactional writes, and executing reactive scans. It also briefly mentions the React hook for state management.

import { TupleDatabaseClient, TupleDatabase, InMemoryTupleStorage, transactionalReadWrite } from "tuple-database";

// 1. Define your schema using TypeScript types.
type User = {
  id: string;
  first_name: string;
  last_name: string;
  age: number;
};

type UserIndex = {
  key: ["user", { id: string }],
  value: User;
};

type AgeIndex = {
  key: ["userByAge", { age: number }, { id: string }],
  value: null;
};

type Schema = UserIndex | AgeIndex;

// 2. Construct your database with an in-memory storage.
const db = new TupleDatabaseClient<Schema>(new TupleDatabase(new InMemoryTupleStorage()));

// 3. Define a transactional write query.
const insertUser = transactionalReadWrite<Schema>()((tx, user: User) => {
  const { id, first_name, last_name, age } = user;
  tx.set(["user", { id }], user);
  tx.set(["userByAge", { age }, { id }], null);
});

// 4. Insert some data.
insertUser(db, { id: "1", first_name: "Chet", last_name: "Corcos", age: 31 });
insertUser(db, { id: "2", first_name: "Tanishq", last_name: "Kancharla", age: 22 });
console.log("Users inserted.");

// 5. Define a read query to get users by age.
function getUsersByAge(dbClient: TupleDatabaseClient<Schema>, minAge: number) {
  return dbClient.scan({ prefix: ["userByAge", { age: minAge }], gte: ["userByAge", { age: minAge }] });
}

// 6. Execute a read query and log results.
const usersOver30 = getUsersByAge(db, 30);
console.log("Users with age >= 30:", usersOver30.map(entry => entry.key[2].id));

// For React integration:
// import { useTupleDatabase } from 'tuple-database/useTupleDatabase';
// function App({db}: {db: TupleDatabaseClient<Schema>}) {
//   const oldestUser = useTupleDatabase(db, () => {
//     const [oldestEntry] = db.scan({prefix: ["userByAge"], reverse: true, limit: 1});
//     return oldestEntry ? db.get(["user", {id: oldestEntry.key[2].id}]) : null;
//   }, []);
//   return <div>The oldest user is age: {oldestUser?.age}</div>;
// }