Registry / database / couchset

couchset

JSON →
library0.3.0jsnpmunverified

CouchSet is a Couchbase ORM/model layer for TypeScript and Node.js. Current stable version is 0.3.0, released with weekly cadence. It provides both a legacy default API and a modern API under 'couchset/next' for gradual migration. Key differentiators: built-in TypeScript types, schema support, soft delete, paginated queries, and automatic reconnect. Compared to mongoose for MongoDB, CouchSet is purpose-built for Couchbase with N1QL support.

npm install couchset
INSTALL
IMPORT
SIG · COUCHSET
C
couchset
databasejavascriptv0.3.0
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.

couchset
import { couchset } from 'couchset/next'
import { couchset } from 'couchset'
Legacy default import from 'couchset' uses deprecated API. Use 'couchset/next' for modern API.
Model
import { Model } from 'couchset/next'
import Model from 'couchset'
Model is a named export, not default. Modern API in 'couchset/next' provides additional features like indexes.
startCouchbase
import { startCouchbase } from 'couchset/next'
const { startCouchbase } = require('couchset')
Use ESM import for 'couchset/next'. The legacy default entrypoint does not export startCouchbase.
health
import { health, ready, shutdown } from 'couchset/next'
import { health } from 'couchset'
Health check exports are only available in 'couchset/next'. Legacy default missing.

Modern API setup: connect to Couchbase, define a model with indexes, perform CRUD operations, and run paginated queries.

import { couchset, Model } from 'couchset/next'; // Define a User type and model type User = { userId: string; email?: string; }; const users = new Model('User', { schema: { createdAt: 'date', updatedAt: 'date', }, indexes: [ { name: 'idx_user_userId', fields: ['userId'], }, ], }); // Connect to Couchbase await couchset({ connectionString: process.env.COUCHBASE_URL || 'couchbase://localhost', username: process.env.COUCHBASE_USERNAME || 'admin', password: process.env.COUCHBASE_PASSWORD || '1234', bucketName: process.env.COUCHBASE_BUCKET || 'dev', }); await couchset.ready(); // Insert a document const created = await users.insert<User>({ userId: 'ceddy', email: 'ceddy@example.com', }); // Get by ID const found = await users.getById<User>(created.id); // Patch with $set const patched = await users.patchById<User>(created.id, { $set: { email: 'new@example.com' }, }); // Paginated query const page = await users.page<User>({ where: { userId: { $eq: 'ceddy' } }, limit: 25, page: 0, }); // Delete (hard delete) await users.deleteById(created.id, { hard: true });
Debug
Known issues
breakingLegacy default entrypoint 'couchset' has different API than 'couchset/next'. Mixing imports from both can cause unexpected behavior.
fix
Use 'couchset/next' for all new code. For existing projects, migrate gradually following the migration guide.
affects: <0.3.0
deprecatedcouchset() in legacy default does not return a promise; it returns a connection object. In 'couchset/next', couchset() is async and must be awaited.
fix
Use await couchset(...) in modern API. If using legacy, ensure connection is established before operations.
affects: <0.3.0
gotchaModel.deleteById() defaults to soft delete unless { hard: true } is passed. Missing hard delete flag will only mark as deleted, not actually remove the document.
fix
Explicitly provide { hard: true } for permanent deletion, or set softDelete: false in model options.
affects: >=0.3.0
gotchaEnvironment variable COUCHSET_RECONNECT must be exactly 'false', '0', or 'no' to disable reconnect. Any other value (e.g., 'false' with capital F?) will treat reconnect as enabled.
fix
Set COUCHSET_RECONNECT=false or COUCHSET_RECONNECT=0 to disable auto-reconnect.
affects: >=0.3.0
Errors
Common errors & fixes
TypeError: couchset is not a function
Using default import from 'couchset' when named import is required.
fix
Use import { couchset } from 'couchset/next' or { couchset } from 'couchset' (legacy) instead of import couchset from 'couchset'.
Model 'User' is not ready: connection not established
Calling model methods before awaiting couchset.ready()
fix
Add await couchset.ready() after calling couchset() before performing any model operations.
Bucket not found: 'dev'
Specified bucket does not exist in Couchbase cluster or Couchbase server not running.
fix
Verify bucket name and ensure Couchbase cluster is accessible. For local development, use 'couchbase://localhost' and create bucket 'dev' via admin UI.
TypeError: Cannot read properties of undefined (reading 'insert')
Using legacy API with modern model instance or vice versa.
fix
Consistently use either 'couchset' (legacy) or 'couchset/next' (modern) for all imports and model method calls. They are not interchangeable.
Upgrade
Version history
0.3.0latest on npm
Audit
Dependencies
couchbaserequiredOfficial Couchbase Node.js SDK required for cluster operations
Agent activity
13 hits · last 30 days
node
10
OpenAI (training)
1
Resources
couchset — npm install couchset · libregistry