API reference
Public entrypoints, methods, helpers, and return shapes.
Concise inventory of public surfaces. Prefer the topic guides for behavior, pitfalls, and examples; this page is for what is exported and return shapes.
Entrypoints
| Import | Purpose |
|---|---|
couchset / couchset/legacy | Legacy-compatible API |
couchset/next | Modern API and client primitives |
couchset/register | Runtime TypeScript registration |
couchset/register/transpile-only | Registration without type checking |
couchset/register/type-check | Registration with type checking |
Model inventory
Reads
getById, findByIdWithMeta, getWithCas, findMany, findOne, exists, count, page
findManydefaults to 10 rows / page0;findOneforces limit1.throwOnError: falseconverts query failures to empty /null/false/0.countandexistsreject includes.- Key-value
getByIdthrows SDK not-found;findOnereturnsnull. findByIdWithMeta/getWithCasreturn{ content, cas, expiryTime? }.- Model
pagereturns{ items, hasNext, pageInfo }withlimit,page,offset, and nullablenextPage/nextOffset.
Guide: CRUD and queries, Relationships and hydration.
Writes
insert, prepareInsert, upsert, replaceById, prepareReplace, replaceIfCas, patchById, incrementById, mutateById, deleteById, consumeOnce
Soft deletion: softDeleteById, restoreById, withDeleted, onlyDeleted, withoutDefaultWhere.
Hydration: findDocById, findDocOne, hydrate.
SQL++ and keyspace
queryRows, queryOne, queryPage, bucket, keyspace, from
Indexes: indexStatements, instance / static ensureIndexes.
Low-level: getCollection, parse, parseProjection, serialize, serializeField.
Client inventory
| Area | Methods |
|---|---|
| Lifecycle | ready, shutdown, getConnection |
| Registry | model, registerModel, definitions, keyspace |
| Collections | planCollections, ensureCollections, combined provision |
| GSI | planIndexes, applyIndexPlan, ensureIndexes |
| Search | search, planSearchIndexes, applySearchIndexPlan |
| Other | geo, transaction, eventing |
planCollectionsreports create / matching targets.provision({ collections?, indexes?, waitForIndexes? })returns collection results and index statements.- Registration provisions only with an explicit
provisionoption. keyspace(definition)renders bucket + target without connecting, provisioning, or requiring registration.
Guides: Connections, Provisioning, Search.
Transactions and scoped views
CouchsetTransaction: model(definition), attempt-bound query(statement, options) -> { rows }.
TransactionModel: nullable get / getById, insert(id, data), replace(document, data), replaceById(id, data), remove(document), query. Pass the returned transaction document to replace / remove. tx.model(definition) binds/registers on demand but never provisions.
ScopedModel: chainable named scopes, inspect(), findMany, findOne, page, exists, count; forwards withDeleted / onlyDeleted / withoutDefaultWhere while retaining scope predicates.
Guides: Provisioning and transactions, Extensions.
Composition and helpers
| Group | Exports |
|---|---|
| Definitions | defineModel, defineModelPlugin, dateCodec |
| Validation / hooks | withModelValidator, ModelValidationError, ModelAfterHookError |
| Relationships / views | joinField, withModelScopes, ScopedModel, withModelMethods, withDocumentMethods |
| Bulk | bulkMap, withModelBulk |
| Geo | ModelGeo (withinBox, withinRadius), geoPoint, geoBounds, geoRadiusKm, radiusBounds |
| Search | ModelSearch (query, match, vector, withinRadius, withinBox, withinPolygon, shape), buildModelSearchIndex |
| Eventing | Eventing (definitions, register, define, physicalName, plan, apply, pause, remove), createEventing, createEventingWithManager, defineEventingFunction |
| Tests / series | createCouchsetTestFixture; TimeSeriesModel (chunkId, buildChunk, appendChunk, rangeQuery, range, queryRows); intervalToMilliseconds |
Modern runtime exports also include singleton helpers: couchset, couchsetServerless, ready, ping, health, shutdown, ensureIndexes, CouchbaseConnection, startCouchbase, startCouchbaseServerless, parseDatabaseUrl, getConnectionOptions, connectionOptions, plus query builders (QueryBuilder, selectBuilder, buildSelectExpr, buildWhereClauseExpr, buildIndexExpr, buildSelectArrayExpr, query exception classes/dictionaries, parseStringSelectExpr, escapeReservedWords, CustomQuery, Pagination, createUpdate).
Type-only exports cover model / read / query / include / index / TTL / connection / pagination / search / geo / plugin / hook / instrumentation / Eventing / transaction / time-series contracts — they do not exist at runtime.
Internal client helpers (UUID, keyspace, index, raw where builders) are not package-root exports. Lower-level public builders do not automatically apply model filters, codecs, validation, hooks, or authorization.
Key returns
| Shape | Fields |
|---|---|
| Model page | { items, hasNext, pageInfo: { limit, page, offset, nextPage, nextOffset } } |
| Raw query page | { items, hasNext, params } |
| CAS read | { content, cas, expiryTime? } |
| Consume | { status: 'consumed' | 'missing' | 'conflict' } |
| Bulk item | { index, status: 'fulfilled', value } / { index, status: 'rejected', error } / { index, status: 'skipped' } |
SDK options and results retain Couchbase SDK types. Refer to that SDK for durability, timeout, consistency, mutation token, Search, and transaction option details.