Node Adapters
Relevant source files
The following files were used as context for generating this wiki page:
The Node Adapters provide a platform-specific implementation of core interfaces (Cache, Database, and Environment) for running the FOSSBilling API within a Node.js runtime. While the primary deployment target is Cloudflare Workers, these adapters ensure the application remains runtime-agnostic and support alternative deployments or local testing scenarios.
Sources: README.md:12-16, AGENTS.md:5-7
Architecture Overview
The Node adapter system is designed to mirror the Cloudflare Workers environment bindings. It maps standard Node.js capabilities (such as node:sqlite and process.env) to the internal interfaces used by the service logic.
This diagram illustrates how the Service Layer interacts with the Node-specific implementations of required platform bindings.
Sources: src/lib/adapters/node/index.ts, AGENTS.md:5-7
Database Adapter
The Node database adapter utilizes the native node:sqlite module to provide a compatible interface for database operations. It supports both in-memory databases and file-based persistence.
SQLiteAdapter Class
The SQLiteAdapter implements the standard database interface, providing methods to prepare and execute SQL statements. It wraps the synchronous DatabaseSync object from Node.js.
| Component | Description |
|---|---|
SQLiteAdapter | Main class wrapping a DatabaseSync instance. |
prepare(query) | Returns a prepared statement object for execution. |
batch(statements) | Executes multiple statements within a single transaction. |
createInMemoryDatabase() | Utility to initialize a :memory: SQLite instance. |
createFileDatabase(path) | Utility to initialize an SQLite instance at a specific filesystem path. |
Sources: src/lib/adapters/node/database.ts:15-130, test/lib/adapters/node/database.test.ts:10-150
Statement Handling
Prepared statements in the Node adapter support chaining via the bind() method and provide three primary execution paths:
all(): Returns all rows matching the query.first(): Returns the first row matching the query or null.run(): Executes the query and returns metadata (e.g.,changes,last_row_id).
Sources: src/lib/adapters/node/database.ts:40-100, test/lib/adapters/node/database.test.ts:35-110
Environment Adapter
The NodeEnvironmentAdapter provides a bridge to Node.js environment variables. It abstracts access to process.env, allowing the application logic to retrieve configuration without direct dependency on the Node global object.
Key Functions
get(key: string): Retrieves the string value fromprocess.env.has(key: string): Returns a boolean indicating if the environment variable is defined.
Sources: src/lib/adapters/node/environment.ts:10-22
Bindings Initialization
The createNodeBindings function is the primary entry point for setting up the Node adapter environment. It normalizes paths and initializes all required adapters (Cache, Database, and Environment).
Path Normalization
The adapter handles various path formats for database initialization, ensuring that file extensions (like .db, .sqlite, or .sqlite3) are handled correctly or defaulting to in-memory storage if no path is provided.
| Input Scenario | Resulting Storage |
|---|---|
undefined or Empty | In-memory database |
/path/to/file.db | Persistent file-based SQLite |
/path/without/ext | Persistent file-based SQLite |
Sources: src/lib/adapters/node/index.ts:10-40, test/lib/adapters/node/bindings.test.ts:10-55
// Example: Creating Node Bindings
const bindings = createNodeBindings("/tmp/api-storage.db");
// bindings.databases.DB_EXTENSIONS is now a persistent SQLiteAdapter
// bindings.environment is a NodeEnvironmentAdapter
Sources: src/lib/adapters/node/index.ts:25-50, test/lib/adapters/node/index.test.ts:5-15
Summary
Node Adapters enable the FOSSBilling API to function outside of the Cloudflare Workers ecosystem by providing high-fidelity implementations of platform interfaces. By wrapping Node's native SQLite and environment capabilities, the project ensures that core service logic remains portable and testable across different JavaScript runtimes.
Sources: README.md:12-16, AGENTS.md:5-7, src/lib/adapters/node/index.ts