Baselet

0.3.0 verified Thu Apr 23 auth: no javascript

Baselet is a lightweight, file-system based database library for JavaScript and TypeScript applications, currently at version 0.3.0. It leverages `disklet` for persistent storage, allowing it to store data directly on disk without requiring external database servers. This makes it suitable for embedded applications, local storage, or serverless environments where a simple, durable key-value or document store is needed. Its primary differentiators include its small footprint, direct disk interaction via `disklet`, and a focus on simplicity. As a 0.x package, it is still under active development, and its API might evolve with subsequent minor versions, though a regular release cadence isn't yet established. Developers should anticipate potential API adjustments.

Common errors

error TypeError: db.getJson is not a function ↓

cause The 'db' object is not a valid Baselet instance, possibly due to incorrect initialization, missing import, or an outdated Baselet version with a different API.

fix

Ensure you are calling makeBaselet correctly with a Disklet instance and a string path, and that Baselet is properly imported and the correct methods are being called.

error Error: Path exists but is not a directory ↓

cause The path provided to `makeBaselet` or the underlying `disklet` factory already exists but is a file, or is inaccessible/read-only, preventing Baselet from initializing its directory structure.

fix

Choose a new, empty directory path for your Baselet instance, or ensure the existing path is a writable directory and not a file.

error Module not found: Error: Can't resolve 'baselet' or Cannot find module 'baselet' ↓

cause The 'baselet' package is not installed or not correctly linked in your project's `node_modules`.

fix

Run npm install baselet disklet or yarn add baselet disklet to ensure both Baselet and its core disklet dependency are installed and available.

Warnings

breaking As a 0.x package, the API of Baselet is subject to change without strict adherence to semantic versioning. Methods, signatures, or error handling might be modified in minor or patch releases. ↓

fix Refer to the official GitHub repository's changelog or latest source code for API updates between versions. Pinning to exact patch versions is recommended for stability.

gotcha Baselet's persistence depends entirely on the underlying 'disklet' instance. If using a memory-based disklet (e.g., `makeMemoryDisklet`), data will not persist across application restarts. ↓

fix For persistent storage, ensure you use a file-system based disklet (e.g., `makeNodeDisklet` for Node.js or `makeReactNativeDisklet` for React Native) and provide a stable, writable path.

gotcha Directly manipulating files within the Baselet's storage path via disklet (or the underlying file system) outside of Baselet's API can lead to data corruption or unexpected behavior. ↓

fix Always use the Baselet API methods (e.g., `setJson`, `getJson`, `delete`) for all data operations within its managed database path to ensure data integrity.

Install

npm install baselet

yarn add baselet

pnpm add baselet

Imports

makeBaselet
wrong
```
const makeBaselet = require('baselet')
```
correct
```
import { makeBaselet } from 'baselet'
```
Use this factory function to initialize a Baselet database instance. It requires a Disklet instance and a path.
Baselet
wrong
```
import type Baselet from 'baselet'
```
correct
```
import { Baselet } from 'baselet'
```
This is the TypeScript interface defining the Baselet instance API. Use it for type annotations; it's not a runtime construct.
makeBaselet (CommonJS)
```
const { makeBaselet } = require('baselet')
```
For CommonJS environments. Given its current version (0.x), Baselet generally supports CJS alongside ESM, but ESM is recommended for new projects.

Quickstart

Initializes an in-memory Baselet database, demonstrating how to store and retrieve JSON objects and raw text. Requires `disklet`.

import { makeBaselet, Baselet } from 'baselet'
import { makeMemoryDisklet } from 'disklet' // Or makeNodeDisklet for Node.js, makeReactNativeDisklet for React Native

async function runBaseletExample() {
  // 1. Create a disklet instance (using in-memory for this example, use file-system for persistence)
  const disklet = makeMemoryDisklet()
  const dbPath = 'my-app-data'

  // 2. Initialize Baselet database
  const db: Baselet = makeBaselet(disklet, dbPath)
  console.log(`Baselet database initialized at path: ${dbPath}`)

  // 3. Store some JSON data
  const userId = 'user123'
  const userData = { name: 'Alice', email: 'alice@example.com', age: 30 }
  await db.setJson(userId, userData)
  console.log(`Stored user data for ${userId}`)

  // 4. Retrieve JSON data
  const retrievedUserData = await db.getJson(userId)
  console.log(`Retrieved user data for ${userId}:`, retrievedUserData)

  // 5. Store a simple string
  await db.setText('last-access', new Date().toISOString())
  console.log('Stored last access time.')

  // 6. Retrieve simple string
  const lastAccess = await db.getText('last-access')
  console.log('Last access time:', lastAccess)

  // 7. Attempt to retrieve a non-existent key (should throw or reject)
  try {
    await db.getJson('non-existent-key')
  } catch (error) {
    console.log(`Attempted to get non-existent key: ${(error as Error).message}`)
  }
}

runBaseletExample().catch(console.error)