@fnndsc/cumin

  ____                _
 / ___|   _ ___  ____(_)_ __
| |  | | | | '_ \| '_ \| '_ \
| |__| |_| | | | | | | | | | |
 \____\__,_|_| |_|_| |_|_| |_|

Cumin Underpins Management Infrastructure Needs

cumin is the infrastructure and state management layer of the ChRIS interface ecosystem. It is a backend library that handles the "dirty work" of connecting to ChRIS, managing authentication tokens, and persisting user sessions.

Installation

npm install @fnndsc/cumin

Requires Node.js ≥ 20.12. Ships with TypeScript type definitions.

Usage

import { ChRISConnection, ChrisContext, ChrisIO } from "@fnndsc/cumin";

// The context engine remembers the active user, CUBE URL, and working directory
const context = new ChrisContext();
await context.init();
const cubeURL: string | null = await context.ChRISURL_get();

See Core Features for the full API surface.

Abstract

cumin abstracts the ChRIS REST API into a stateful, object-oriented environment. It is responsible for:

1. Connection Management: Handling authentication, token storage, and client initialization.
2. Context Persistence: Implementing the "Context" engine that remembers the active User, CUBE URL, and Working Directory.
3. IO & Storage: Providing an abstraction (IStorageProvider) for filesystem access, enabling support for both Node.js (via fs) and other environments.

Role in the Ecosystem

In the "Sandwich Model" architecture, cumin is the bottom layer (just above the raw API client).

• Consumers: Primarily salsa (logic) and chili (CLI state).
• Environment: Designed for Node.js but architected with interfaces to support browser environments.

Core Features

• ChrisContext: The state machine for multi-tenant, multi-backend sessions.
• ChRISConnection: Wrapper for the low-level API client.
• IStorageProvider: Abstraction interface for reading/writing config and data.
  • Includes readBinary for binary file uploads.
  • Includes recursive directory traversal helpers.
• ChrisIO: High-level IO operations, including recursive directory uploading (uploadLocalPath).
• ChRISResource.resources_getAll(): Generic pagination handler.
• ListCache (listCache_get()): Session-scoped directory listing cache for the VFS.
• ProcCache (procCache_get()): Session-scoped job monitoring DAG with versioned, identity-scoped daemon checkpoints. Restored topology remains usable while CUBE reconciliation runs; terminal status persists and active status refreshes on read. Powers the /proc/jobs/ VFS provider in salsa.

Developer Setup

To build the cumin library from source:

1. Install dependencies:

   npm install
   

2. Compile:

   npm run build
   

License

MIT — part of the ChRIS Project.

-30-