{"id":44094,"library":"userlandstorage","title":"userland storage","description":"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.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/scripting/userland/tree/main/storage","tags":["javascript"],"install":[{"cmd":"npm install userlandstorage","lang":"bash","label":"npm"},{"cmd":"yarn add userlandstorage","lang":"bash","label":"yarn"},{"cmd":"pnpm add userlandstorage","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for database operations. Not a hard peer dependency but required at runtime.","package":"mysql2","optional":true}],"imports":[{"note":"The package does not export a default export in CJS style; use ESM import.","wrong":"const storage = require('userlandstorage')","symbol":"default import","correct":"import storage from 'userlandstorage'"},{"note":"Named export for the Storage class. This is the main entry point.","wrong":null,"symbol":"Storage constructor","correct":"import { Storage } from 'userlandstorage'"},{"note":"Named export for creating a file; also available as a method on Storage instance.","wrong":null,"symbol":"createFile","correct":"import { createFile } from 'userlandstorage'"},{"note":"Named export for reading a file; may be used directly without instantiating Storage.","wrong":null,"symbol":"readFile","correct":"import { readFile } from 'userlandstorage'"}],"quickstart":{"code":"import { Storage } from 'userlandstorage';\n\nconst storage = new Storage({\n  host: process.env.DB_HOST ?? 'localhost',\n  user: process.env.DB_USER ?? 'root',\n  password: process.env.DB_PASS ?? '',\n  database: process.env.DB_NAME ?? 'userland'\n});\n\nasync function example() {\n  await storage.init();\n\n  // Create a file\n  const fileId = await storage.createFile({\n    username: 'alice',\n    relpath: '/notes/hello.txt',\n    type: 'text/plain',\n    contents: 'Hello, world!',\n    flprivate: false\n  });\n\n  // Read the file\n  const file = await storage.readFile(fileId);\n  console.log(file.contents);\n\n  // Update the file\n  await storage.updateFile(fileId, { contents: 'Updated content' });\n\n  // Delete the file\n  await storage.deleteFile(fileId);\n\n  await storage.close();\n}\n\nexample().catch(console.error);","lang":"typescript","description":"Creates a Storage instance, initializes the database, and demonstrates CRUD operations on a file."},"warnings":[{"fix":"Ensure MySQL/MariaDB is accessible and the table 'storage' is created (use init() or run the SQL schema manually).","message":"The package requires a running MySQL database. No bundled SQLite or in-memory fallback.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Avoid storing binary data or very large contents; consider using a BLOB column or external storage.","message":"File contents are stored as text in MySQL TEXT column. Large files may hit MySQL's max_allowed_packet limit.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure MySQL 8.0+ or MariaDB 10.2+ for automatic JSON default support.","message":"The 'metadata' column uses JSON default in MySQL 8+. Older MySQL versions may not support default JSON_OBJECT and will return NULL.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use import statements or set type: 'module' in package.json.","message":"The package uses ES modules (ESM) only. CommonJS require will not work.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"search_vec":"'0.4.2':20 'access':52 'api':34 'applic':12 'base':7 'cadenc':90 'cloud':56 'control':53 'creat':36 'current':22,88 'databas':62,82 'database-on':61 'delet':39 'design':65 'file':17,40 'frequent':86 'ident':71 'identifi':41 'integr':68 'javascript':93 'lightweight':76 'low':92 'metadata':49 'mysql/mariadb':81 'node.js':11 'packag':74 'part':25 'path':46 'per':15 'per-us':14 'project':29 'provid':31 'public/private':54 'read':37 'relat':45 'releas':23,89 'reli':78 'requir':13 'sdks':58 'simpl':4 'sql':6 'sql-base':5 'storag':2,8,18,57 'straightforward':33 'system':9,72 'type':50 'unlik':55 'updat':38,87 'user':16 'userland':1,28 'usernam':43 'version':19","created_at":"2026-06-05T17:02:57.082022+00:00","updated_at":"2026-06-05T17:02:57.082022+00:00","problems":[{"fix":"Run 'npm install userlandstorage' and ensure it is in package.json dependencies.","cause":"Package not installed or npm install failed.","error":"Error: Cannot find module 'userlandstorage'"},{"fix":"Use 'import { Storage } from 'userlandstorage'' instead of 'import storage from ...'","cause":"Using default import incorrectly; Storage is a named export.","error":"TypeError: storage is not a constructor"},{"fix":"Run MySQL command: ALTER USER 'youruser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword';","cause":"MySQL user authentication plugin not compatible with mysql2 driver (commonly caching_sha2_password).","error":"ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol"},{"fix":"Ensure contents property is a string. Convert Buffer to string before passing.","cause":"Passing a Buffer or object instead of a string for file contents.","error":"TypeError: contents.replace is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/scripting/userland/tree/main/storage","github":"https://github.com/scripting/userland/tree/main/storage","docs":null,"changelog":null,"pypi":null,"npm":"userlandstorage","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}