@maykonpaulo/maestro-provider-couchbase

📖 Guia completo — criar o admin de qualquer sistema: está no README do pacote @maykonpaulo/maestro-server no npm → https://www.npmjs.com/package/@maykonpaulo/maestro-server

A Couchbase provider for @maykonpaulo/maestro-core — continuing ADR 0007 — Universal Provider Strategy into the document-family, alongside provider-mongodb. It implements all three of the core's provider contracts against a real Couchbase Server (7+) cluster:

• IntrospectionProvider — discovers collections in the configured scope and infers each one's shape via N1QL sampling. Every entity is reported with schemaless: true.
• DatasourceProvider — findById/create/update/delete use real Couchbase KV operations; list/count use N1QL (client-side filter/sort/pagination, same as this family's Cassandra/Neo4j providers).
• SchemaWriteProvider — ensureEntity really creates the missing scope/collection via Couchbase's Collection Management API — a genuine idempotent operation, unlike Firestore/Neo4j's documented no-ops.

Why a separate package instead of a dialect of provider-mongodb

Couchbase's bucket/scope/collection model and N1QL query language are close in spirit to Mongo's document model but structurally distinct (an explicit scope hierarchy, a real collection-management DDL, KV operations separate from its query engine) — ADR 0007 groups providers by paradigm, and Couchbase earns its own package the same way provider-redis did within the same broader document/key-value family.

Installation

npm install @maykonpaulo/maestro-provider-couchbase @maykonpaulo/maestro-core

@maykonpaulo/maestro-core and couchbase are peer dependencies — install the versions your project already uses. couchbase ships prebuilt native binaries for common platforms; no local C++ toolchain is required to install it under normal circumstances.

Usage

import { runIntrospectionProvider } from '@maykonpaulo/maestro-core';
import { createCouchbaseProvider } from '@maykonpaulo/maestro-provider-couchbase';

const provider = createCouchbaseProvider({
  connectionString: 'couchbase://localhost',
  username: 'Administrator',
  password: 'password',
  bucket: 'app',
});

// Introspection — N1QL sampling, validated/normalized via the core
const { result } = await runIntrospectionProvider(provider);

// Real CRUD against the same bucket
const created = await provider.create({ table: 'users', primaryKey: 'id', data: { name: 'Ada' } });

// Create the scope/collection if it isn't there yet
await provider.ensureEntity({ entity: { table: 'tags', fields: [] } });

Configuration

export interface CouchbaseProviderOptions {
  connectionString?: string;  // a couchbase://... or couchbases://... connection string
  username?: string;
  password?: string;
  cluster?: Cluster;          // an already-connected cluster — for tests/embedding; caller owns its lifecycle
  bucket: string;              // required — Couchbase has no "current bucket" to infer
  scope?: string;               // defaults to '_default'
  maxDocuments?: number;       // caps documents read per collection during introspection — unset by default (scans the whole collection)
}

Exactly one of connectionString or cluster must be provided.

id handling

Couchbase documents are addressed by a KV document key, which does not have to equal any field inside the document body. create() without a supplied primaryKey value generates a randomUUID() string and uses it as both the KV key and the primaryKey-named field's value in the returned record, matching every other provider in this monorepo without a native auto-ID concept (e.g. provider-redis).

What is introspected

Since there is no system catalog for arbitrary JSON documents, introspection scans every document in every collection of the configured scope by default (maxDocuments is unset unless you explicitly cap it) via N1QL SELECT d.* FROM ... AS d, and infers fields, nullability and types the same way provider-mongodb does. schemaless: true is set on every entity for the same honesty reason documented there — a document written a moment after this scan can still introduce a field this result never saw.

What is not introspected (known limitations)

• Relations — Couchbase has no foreign-key constraint to read, same reasoning as every other NoSQL provider in this monorepo; relations is always [].
• Indices — not introspected in this version.
• N1QL query readiness — list/count/introspection all require a usable index (typically a primary index) on the target collection; a freshly created collection with no index will error on N1QL queries until one exists. This provider does not create indexes on the caller's behalf — that is a deployment/schema-provisioning concern, deliberately out of scope for ensureEntity (see below).
• N1QL scan consistency — list/count/introspection all query with RequestPlus scan consistency, trading extra query latency for the guarantee that a document just written via create() is visible to the very next list()/count()/introspect() call. Without this, N1QL's default (NotBounded) can lag behind KV writes.

Schema creation (ensureEntity)

Unlike Firestore/Neo4j, Couchbase's Collection Management API makes collection existence and creation unambiguous: ensureEntity checks the configured scope's collections (creating the scope first if it doesn't exist yet) and creates the collection if missing, returning created: true/false accordingly. entity.fields is not applied to the created collection — there is nothing in Couchbase's own model to apply column definitions to. This does not create a query index — a newly created collection accepts KV operations (create/findById/update/delete) immediately, but list/count/introspect (which use N1QL) require an index to be provisioned separately.

Testing

Unit tests (tests/couchbase-provider-construction.test.ts) cover constructor validation only, no Docker required. Integration tests (tests/couchbase-integration.test.ts) run against a real Couchbase Server started per test run via @testcontainers/couchbase — run them with pnpm test:integration (requires a running Docker daemon; Couchbase is notoriously slow to become query-ready, so this package's vitest.integration.config.ts uses a more generous timeout than most providers in this monorepo).

Turnkey admin (point at your database, get a UI)

This provider plugs straight into the Maestro turnkey layer: install @maykonpaulo/maestro-server and @maykonpaulo/maestro-admin, point them at your database and get a full governed admin (list/CRUD/RBAC/audit + a metadata-driven UI) with no per-entity code.

import { createCouchbaseProvider } from '@maykonpaulo/maestro-provider-couchbase';
import { createMaestroServer, createIntrospectedEngine } from '@maykonpaulo/maestro-server';

const provider = createCouchbaseProvider({ connectionString: 'couchbase://localhost', username: 'Administrator', password: 'password', bucket: 'app' });
const engine = await createIntrospectedEngine({ provider, access: 'full' });
await createMaestroServer({ engine }).listen(3000);

See the Turnkey admin guide.