userlandstorage

library0.4.2jsnpmunverified

A simple SQL-based storage system for Node.js applications requiring per-user file storage. Version 0.4.2 is current, released as part of the userland project. It provides a straightforward API to create, read, update, delete files identified by username and relative path, each with metadata, type, and access control (public/private). Unlike cloud storage SDKs, it is database-only and designed to be integrated with any identity system. The package is lightweight and relies on a MySQL/MariaDB database. It is not frequently updated; current release cadence is low.

storage database

npm install userlandstorage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · USERLANDSTORAGE

userlandstorage

storagejavascriptv0.4.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default import

✓ import storage from 'userlandstorage'

✗ const storage = require('userlandstorage')

The package does not export a default export in CJS style; use ESM import.

Storage constructor

✓ import { Storage } from 'userlandstorage'

Named export for the Storage class. This is the main entry point.

createFile

✓ import { createFile } from 'userlandstorage'

Named export for creating a file; also available as a method on Storage instance.

readFile

✓ import { readFile } from 'userlandstorage'

Named export for reading a file; may be used directly without instantiating Storage.

Creates a Storage instance, initializes the database, and demonstrates CRUD operations on a file.

import { Storage } from 'userlandstorage'; const storage = new Storage({ host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'userland' }); async function example() { await storage.init(); // Create a file const fileId = await storage.createFile({ username: 'alice', relpath: '/notes/hello.txt', type: 'text/plain', contents: 'Hello, world!', flprivate: false }); // Read the file const file = await storage.readFile(fileId); console.log(file.contents); // Update the file await storage.updateFile(fileId, { contents: 'Updated content' }); // Delete the file await storage.deleteFile(fileId); await storage.close(); } example().catch(console.error);

Debug

Known issues

gotchaThe package requires a running MySQL database. No bundled SQLite or in-memory fallback.

fix

Ensure MySQL/MariaDB is accessible and the table 'storage' is created (use init() or run the SQL schema manually).

affects: >=0.0.0

gotchaFile contents are stored as text in MySQL TEXT column. Large files may hit MySQL's max_allowed_packet limit.

fix

Avoid storing binary data or very large contents; consider using a BLOB column or external storage.

affects: >=0.0.0

gotchaThe 'metadata' column uses JSON default in MySQL 8+. Older MySQL versions may not support default JSON_OBJECT and will return NULL.

fix

Ensure MySQL 8.0+ or MariaDB 10.2+ for automatic JSON default support.

affects: >=0.0.0

gotchaThe package uses ES modules (ESM) only. CommonJS require will not work.

fix

Use import statements or set type: 'module' in package.json.

affects: >=0.4.0

Errors

Common errors & fixes

Error: Cannot find module 'userlandstorage'

Package not installed or npm install failed.

fix

Run 'npm install userlandstorage' and ensure it is in package.json dependencies.

TypeError: storage is not a constructor

Using default import incorrectly; Storage is a named export.

fix

Use 'import { Storage } from 'userlandstorage'' instead of 'import storage from ...'

ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol

MySQL user authentication plugin not compatible with mysql2 driver (commonly caching_sha2_password).

fix

Run MySQL command: ALTER USER 'youruser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword';

TypeError: contents.replace is not a function

Passing a Buffer or object instead of a string for file contents.

fix

Ensure contents property is a string. Convert Buffer to string before passing.

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

mysql2optionalUsed internally for database operations. Not a hard peer dependency but required at runtime.

Agent activity

38 hits · last 30 days

node