3. Set the following environment variables before connecting:

COUCHBASE_URL=couchbase://localhost
COUCHBASE_BUCKET=your-bucket
COUCHBASE_USER=admin
COUCHBASE_PASS=password

4. In your application entry point, call connect then start before any model operations, and close on graceful shutdown.

5. If you are using a bundler (esbuild, webpack), mark couchbase and @scarf/scarf as external — they must remain as native Node.js requires.

Public API

connect

import { connect } from './ottoman/source';

async function connect(connectString: string, connectOptions?: ConnectOptions): Promise<Ottoman>

Opens a connection to Couchbase using a connection string of the form couchbase://host/bucket@user:password. Returns the default Ottoman instance. Must be awaited before defining models or running queries.

model

import { model } from './ottoman/source';

function model<T = any>(
  name: string,
  schema: Schema | Record<string, any>,
  options?: ModelOptions
): IModel<T>

Defines and registers a model on the default Ottoman instance. schema can be a Schema instance or a plain object shorthand. options.collectionName overrides the collection used; options.scopeName sets the scope. Returns a constructor whose instances are Document objects.

Schema

import { Schema } from './ottoman/source';

class Schema {
  constructor(fields: Record<string, any>, options?: SchemaOptions)
  add(fields: Record<string, any>): void
  index(name: string, fields: string[], options?: object): void
  pre(hook: string, fn: Function): void
  post(hook: string, fn: Function): void
}

Defines the structure, types, validators, and indexes for a model. Supports embedded documents (EmbedType), references (ReferenceType), custom validators, and lifecycle hooks (pre/post on save, validate, remove).

Query

import { Query } from './ottoman/source';

class Query {
  constructor(conditions: IConditionExpr, bucketName: string)
  select(expressions?: ISelectType[]): this
  where(expr: LogicalWhereExpr): this
  limit(n: number): this
  offset(n: number): this
  orderBy(expr: Record<string, SortType>): this
  build(): string
}

Fluent N1QL query builder. Use build() to produce a raw N1QL string you can pass to the Couchbase cluster. Useful when model-level finders do not cover a complex aggregation or join.

SearchConsistency

import { SearchConsistency } from './ottoman/source';

enum SearchConsistency {
  NONE,
  LOCAL,
  GLOBAL
}

Controls index scan consistency for find and findOne calls. Pass via FindOptions.consistency. Use GLOBAL in tests or write-then-read flows; use NONE for high-throughput reads.

Working examples

Scenario - Connect and define a model

Define a typed User model, persist a document, and retrieve it.

import { connect, model, start, close, Schema } from './ottoman/source';

const userSchema = new Schema({
  name: { type: String, required: true },
  email: { type: String, required: true },
  createdAt: { type: Date, default: () => new Date() },
});

async function main() {
  await connect(
    `couchbase://${process.env.COUCHBASE_URL}/${process.env.COUCHBASE_BUCKET}` +
    `@${process.env.COUCHBASE_USER}:${process.env.COUCHBASE_PASS}`
  );

  const User = model('User', userSchema);

  await start(); // ensures indexes are created

  const user = new User({ name: 'Jane Doe', email: 'jane@example.com' });
  await user.save();
  console.log('Saved user id:', user.id);

  const found = await User.findById(user.id);
  console.log('Found:', found.name);

  await close();
}

main().catch(console.error);

Scenario - Query builder for complex N1QL

Build and log a parameterised N1QL statement without going through a model.

import { Query, buildWhereClauseExpr } from './ottoman/source';

const conditions = {};
const query = new Query(conditions, 'travel-sample')
  .select([{ $field: 'name' }, { $field: 'country' }])
  .where({
    $and: [
      { type: { $eq: 'airport' } },
      { country: { $like: 'United%' } },
    ],
  })
  .orderBy({ name: 'ASC' })
  .limit(20)
  .offset(0);

const n1ql = query.build();
console.log(n1ql);
// SELECT name, country FROM `travel-sample`
// WHERE (type = "airport" AND country LIKE "United%")
// ORDER BY name ASC LIMIT 20 OFFSET 0

Scenario - Schema hooks and validation

Add a pre-save hook to hash a password field and register a custom validator.

import { connect, model, start, close, Schema, addValidators } from './ottoman/source';
import { createHash } from 'crypto';

addValidators({
  strongPassword: (value: string) => {
    if (value.length < 8) throw new Error('Password must be at least 8 characters');
  },
});

const accountSchema = new Schema({
  username: { type: String, required: true },
  password: { type: String, validator: 'strongPassword' },
});

accountSchema.pre('save', async function (this: any) {
  if (this.password) {
    this.password = createHash('sha256').update(this.password).digest('hex');
  }
});

async function run() {
  await connect(`couchbase://localhost/default@admin:password`);
  const Account = model('Account', accountSchema);
  await start();

  const acc = new Account({ username: 'alice', password: 'securePass123' });
  await acc.save();
  console.log('Hashed password stored:', acc.password);

  await close();
}

run().catch(console.error);

File walkthrough

• index.ts - Barrel file; the only import path consumers need.
• couchbase.ts - Thin re-export of Couchbase SDK symbols used internally; do not import directly.
• exceptions/exceptions.ts - Base OttomanError and typed error subclasses thrown by the ODM.
• exceptions/ottoman-errors.ts - Mapping of error codes to human-readable messages.
• handler/find/ - find, findById, FindOptions, and FindByIdOptions implementations.
• handler/store.ts - Core upsert/insert logic invoked by document.save().
• handler/remove.ts - Single-document removal handler.
• handler/remove-many.ts - Bulk removal returning IManyQueryResponse.
• handler/update_many.ts - Bulk update with UpdateManyOptions.
• handler/create-many.ts - Bulk insert helper.
• handler/utils.ts - Shared handler utilities (key building, CAS handling).
• handler/types.ts - Shared handler TypeScript interfaces.
• model/model.ts - Model class: static finders, save, remove, validate, population.
• model/document.ts - Document base class extended by every model instance.
• model/create-model.ts - Factory wiring schema + Ottoman instance into a model constructor.
• model/model.types.ts - saveOptions, ModelTypes enums/interfaces.
• model/hooks/exec-hooks.ts - Runs pre/post hook chains.
• model/index/n1ql/ - N1QL index creation and query generation.
• model/index/refdoc/ - Reference-document index build helpers.
• model/index/view/ - Couchbase View index helpers and query builder.
• model/utils/ - Utilities: array diff, ref-key extraction, store/remove lifecycle orchestration.
• ottoman/ottoman.ts - Ottoman class and module-level singleton helpers (connect, model, start, close, getDefaultInstance).
• plugins/global-plugin-handler.ts - registerGlobalPlugin implementation.
• plugins/global-plugin-handler-error.ts - Error boundary for plugin execution.
• query/query.ts - Query fluent builder class.
• query/helpers/builders.ts - selectBuilder, buildSelectExpr, buildWhereClauseExpr, buildIndexExpr.
• query/helpers/dictionary.ts - AggDict, ResultExprDict, ReturnResultDict constant maps.
• query/interface/query.types.ts - All query-related TypeScript interfaces and union types.
• query/exceptions.ts - Query-specific exception classes.
• query/utils.ts - parseStringSelectExpr, escapeReservedWords.
• schema/schema.ts - Schema class definition.
• schema/types/ - Built-in types: StringType, NumberType, BooleanType, DateType, ArrayType, EmbedType, ReferenceType, MixedType, CoreType.
• schema/helpers/ - validate, applyDefaultValue, buildFields, registerType, addValidators.
• schema/errors/ - ValidationError, BuildSchemaError.
• schema/interfaces/ - IOttomanType, ValidatorOption interfaces.

Common pitfalls and fixes

• Couchbase binary missing - If the prebuilt binary is absent, install build tools (apt install build-essential / xcode-select --install) so node-gyp can compile from source.
• start() not called before queries - N1QL indexes are not ensured until start() resolves; calling find before it causes index not found errors. Always await start() after all models are defined.
• Connection string format - The string must be couchbase://host/bucketName@user:password. Omitting the bucket segment causes a silent connection to the wrong bucket.
• Couchbase Server version mismatch - Ottoman 2.3+ requires Couchbase Server 7.2+. Older servers lack Collections/Scopes; using scopeName/collectionName options on older servers throws runtime errors.
• ESM/CJS interop - Ottoman source uses CommonJS-style imports internally. If your project uses "type": "module", set "moduleResolution": "node16" and use .js extensions in relative imports, or keep Ottoman in a CJS subpackage.
• Multiple Ottoman instances - Calling connect twice creates a second instance. Use getDefaultInstance() to retrieve the existing one rather than reconnecting.

Vibe-coding prompt template

I am integrating the Ottoman ODM source (located at `src/ottoman/source/`) into
my Node.js TypeScript project. The upstream package is `user@example.com`.
I have already read `USAGE.md` which documents the real exports and working examples.

Please help me do the following step-by-step:

1. Verify my `tsconfig.json` has the correct settings for Ottoman (moduleResolution, esModuleInterop, paths alias).
2. Create a `db.ts` connection module that reads COUCHBASE_URL, COUCHBASE_BUCKET, COUCHBASE_USER, COUCHBASE_PASS from environment variables and exports a `connectDB` function using `connect` and `start` from `src/ottoman/source/index.ts`.
3. Define a typed model for [describe your entity] using the `Schema` class and `model` function from the same source.
4. Add a repository layer with `findById`, `find` with pagination (`FindOptions` / `limit` / `offset`), `save`, and `removeById`.
5. Wire the repository into my existing Express route handlers.
6. Show me how to use the `Query` builder for any complex aggregation I describe.

Only use exports that appear in `src/ottoman/source/index.ts`. Do not install the `ottoman` npm package — I am using the embedded source directly.

License and credit

Ottoman is released under the Apache License 2.0. See source/ for the full source or visit the upstream repository. Upstream npm package: user@example.com. Copyright 2021 Couchbase Inc.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。

Mongoose MongoDB Object Modeling for Node.js

Automation, Utilities & Developer Tools

免费