Rocket-Store

Common errors

• TypeError: rs.post is not a function

  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.
  fix For ES Modules: ensure `const rs = await store.Rocketstore();`. For CommonJS: ensure `const rs = require('rocket-store').default;`.

• [] (or unexpected empty result) when fetching data that should exist.

  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.
  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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  Fix: Always use `const rs = await store.Rocketstore();` or `const rs = await store.default();` for ESM imports and initialization.
• gotcha 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`.
  Fix: Use `const rs = require('rocket-store').default;` to correctly import the Rocket-Store instance in CommonJS.

Install

• npm install rocket-store npm
• yarn add rocket-store yarn
• pnpm add rocket-store pnpm

Imports

• rs
  wrong:

  const rs = require('rocket-store');

  correct:

  const rs = require('rocket-store').default;

  For CommonJS, the Rocket-Store instance is accessed via the `.default` property of the module export.
• Rocketstore
  wrong:

  import { Rocketstore } from 'rocket-store';
  const rs = await Rocketstore();

  correct:

  import * as store from 'rocket-store';
  const rs = await store.Rocketstore();

  In ES Modules, the `Rocketstore` factory function is a named export on the namespace object and must be awaited to get the instance.
• default
  wrong:

  import rs from 'rocket-store';

  correct:

  import defaultStore from 'rocket-store';
  const rs = await defaultStore();

  Alternatively in ES Modules, the default export is also a factory function that returns a Promise and must be awaited to get the instance.
• RocketStoreInstance

  import type { RocketStoreInstance, RocketStoreOptions, RocketStoreResult } from 'rocket-store';

  The package ships TypeScript types for the core instance, configuration options, and method results.

Quickstart

Demonstrates basic setup, configuring the storage area, and performing CRUD operations (post, get, delete) with specific keys and wildcard searches.

import * as rsModule from 'rocket-store';
import type { RocketStoreInstance } from 'rocket-store';
import { join } from 'path';
import { tmpdir } from 'os';

const main = async () => {
  const rs: RocketStoreInstance = await rsModule.Rocketstore();

  // Set a custom storage directory (optional, defaults to OS temp dir)
  await rs.setOption({ data_storage_area: join(tmpdir(), 'my-rocket-data') });

  // 1. Post a record
  const postResult = await rs.post("cars", "Mercedes-C200", { owner: "Lisa Simpson", reg: "N3RD" });
  console.log('Posted Mercedes:', postResult);

  // 2. Post another record with an auto-incremented key
  const postResult2 = await rs.post("cars", null, { owner: "Homer Simpson", reg: "DUFF" }, rs._ADD_AUTO_INC);
  console.log('Posted Homer (auto-inc key):', postResult2);

  // 3. Get all records from the 'cars' collection, ordered descending
  const allCars = await rs.get("cars", "*", rs._ORDER_DESC);
  console.log('All cars (descending):', allCars);

  // 4. Get a specific record by key
  const mercedes = await rs.get("cars", "Mercedes-C200");
  console.log('Mercedes record:', mercedes);

  // 5. Delete records matching a wildcard pattern (e.g., all with 'Cede' in key)
  const deleteResult = await rs.delete("cars", "*cede*");
  console.log('Deleted records matching *cede*:', deleteResult);

  // 6. Get remaining records
  const remainingCars = await rs.get("cars", "*");
  console.log('Remaining cars:', remainingCars);
};

main().catch(console.error);