{"id":16523,"library":"rocket-store","title":"Rocket-Store","description":"Rocket-Store is a lightweight, high-performance flat-file database solution for Node.js, currently at version `0.10.20`. It distinguishes itself by directly leveraging the host operating system's file system caching mechanisms for exceptionally fast data storage and retrieval. Designed for scenarios requiring minimal footprint and high throughput, it stores data in JSON format within collections and records, accessible via unique keys. The package requires no complex configuration or setup, defaulting to the OS temporary directory for data storage, and supports both CommonJS and ES Modules. While specific release cadence isn't explicitly defined, frequent updates indicate active maintenance. Its key differentiators include simplicity, asynchronous mutation safety, and a single-file core with few external dependencies, making it an efficient alternative to more complex database systems for specific use cases.","status":"active","version":"0.10.20","language":"javascript","source_language":"en","source_url":"https://github.com/paragi/rocket-store-node","tags":["javascript","storage","database","key","value","store","key-value","flat","file","typescript"],"install":[{"cmd":"npm install rocket-store","lang":"bash","label":"npm"},{"cmd":"yarn add rocket-store","lang":"bash","label":"yarn"},{"cmd":"pnpm add rocket-store","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For CommonJS, the Rocket-Store instance is accessed via the `.default` property of the module export.","wrong":"const rs = require('rocket-store');","symbol":"rs","correct":"const rs = require('rocket-store').default;"},{"note":"In ES Modules, the `Rocketstore` factory function is a named export on the namespace object and must be awaited to get the instance.","wrong":"import { Rocketstore } from 'rocket-store';\nconst rs = await Rocketstore();","symbol":"Rocketstore","correct":"import * as store from 'rocket-store';\nconst rs = await store.Rocketstore();"},{"note":"Alternatively in ES Modules, the default export is also a factory function that returns a Promise and must be awaited to get the instance.","wrong":"import rs from 'rocket-store';","symbol":"default","correct":"import defaultStore from 'rocket-store';\nconst rs = await defaultStore();"},{"note":"The package ships TypeScript types for the core instance, configuration options, and method results.","symbol":"RocketStoreInstance","correct":"import type { RocketStoreInstance, RocketStoreOptions, RocketStoreResult } from 'rocket-store';"}],"quickstart":{"code":"import * as rsModule from 'rocket-store';\nimport type { RocketStoreInstance } from 'rocket-store';\nimport { join } from 'path';\nimport { tmpdir } from 'os';\n\nconst main = async () => {\n  const rs: RocketStoreInstance = await rsModule.Rocketstore();\n\n  // Set a custom storage directory (optional, defaults to OS temp dir)\n  await rs.setOption({ data_storage_area: join(tmpdir(), 'my-rocket-data') });\n\n  // 1. Post a record\n  const postResult = await rs.post(\"cars\", \"Mercedes-C200\", { owner: \"Lisa Simpson\", reg: \"N3RD\" });\n  console.log('Posted Mercedes:', postResult);\n\n  // 2. Post another record with an auto-incremented key\n  const postResult2 = await rs.post(\"cars\", null, { owner: \"Homer Simpson\", reg: \"DUFF\" }, rs._ADD_AUTO_INC);\n  console.log('Posted Homer (auto-inc key):', postResult2);\n\n  // 3. Get all records from the 'cars' collection, ordered descending\n  const allCars = await rs.get(\"cars\", \"*\", rs._ORDER_DESC);\n  console.log('All cars (descending):', allCars);\n\n  // 4. Get a specific record by key\n  const mercedes = await rs.get(\"cars\", \"Mercedes-C200\");\n  console.log('Mercedes record:', mercedes);\n\n  // 5. Delete records matching a wildcard pattern (e.g., all with 'Cede' in key)\n  const deleteResult = await rs.delete(\"cars\", \"*cede*\");\n  console.log('Deleted records matching *cede*:', deleteResult);\n\n  // 6. Get remaining records\n  const remainingCars = await rs.get(\"cars\", \"*\");\n  console.log('Remaining cars:', remainingCars);\n};\n\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates basic setup, configuring the storage area, and performing CRUD operations (post, get, delete) with specific keys and wildcard searches."},"warnings":[{"fix":"Ensure collection and key names adhere to basic file naming conventions, avoiding special characters like `/`, `\\`, `*`, `?`, or other OS-specific forbidden characters. Implement client-side validation for user-provided keys to prevent silent stripping.","message":"Collection names and keys in Rocket-Store do not support path separators, wildcards, or other illegal characters. Such characters are silently stripped, which can lead to unexpected behavior, data not being found, or silent data corruption.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always use `const rs = await store.Rocketstore();` or `const rs = await store.default();` for ESM imports and initialization.","message":"When using Rocket-Store in an ES Module environment, the instance creation function (`store.Rocketstore()` or `store.default()`) returns a Promise and *must* be awaited. Failing to `await` will result in an uninitialized object and subsequent method calls failing with 'is not a function' errors.","severity":"gotcha","affected_versions":">=0.10.0"},{"fix":"Use `const rs = require('rocket-store').default;` to correctly import the Rocket-Store instance in CommonJS.","message":"When importing Rocket-Store in a CommonJS environment, the main instance is exposed via the `.default` property of the module export. Direct `require('rocket-store')` will return the module object, not the callable instance, leading to errors when attempting to use methods like `rs.post`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ES Modules: ensure `const rs = await store.Rocketstore();`. For CommonJS: ensure `const rs = require('rocket-store').default;`.","cause":"The Rocket-Store instance was not correctly initialized or obtained. This usually happens in ESM if `await` was omitted during instance creation, or in CJS if `.default` was not accessed on the `require()` result.","error":"TypeError: rs.post is not a function"},{"fix":"Verify that collection names and keys do not contain any path separators, wildcards, or other special characters that could be silently removed. Inspect the `key` property in the `post` method's return value to confirm the actual key used for storage.","cause":"The key or collection name used for storing or retrieving data contained illegal characters which were silently stripped by Rocket-Store, resulting in a mismatch between the expected and actual stored key/collection name.","error":"[] (or unexpected empty result) when fetching data that should exist."}],"ecosystem":"npm"}