couchset 0.4.1 → 0.5.0

package/README.md

@@ -10,11 +10,12 @@
 
 CouchSet is a Couchbase model layer for TypeScript and Node.js. The default `couchset` entrypoint keeps the legacy API for safe upgrades; the modern API is available from `couchset/next`.
 
-The additive client-owned primitives—typed definitions, explicit provisioning, transaction-bound models, CAS helpers, and safe index plans—are documented in [Next primitives](./docs/next-primitives.md).
+The additive client-owned primitives—typed definitions, explicit provisioning, transaction-bound models, CAS helpers, safe index plans, and Eventing—are summarized below. Their complete operational guide is [Next primitives](./docs/next-primitives.md).
 
 - [Install](#install)
 - [Legacy Default](#legacy-default)
 - [Modern API](#modern-api)
+- [Modern Client Primitives](#modern-client-primitives)
 - [Next primitives](./docs/next-primitives.md)
 - [Connection Lifecycle](#connection-lifecycle)
 - [Models](#models)
@@ -113,6 +114,88 @@ const page = await users.page<User>({
 await users.deleteById(created.id, {hard: true});
 ```
 
+## Modern Client Primitives
+
+`couchset/next` also offers a client-owned API for typed manifests, explicit administrative work, safe operational plans, and Eventing. These are deliberately separate from the singleton `Model` API above.
+
+### Declarative models
+
+```ts
+import {createCouchsetClient, defineModel} from 'couchset/next';
+
+const sessions = defineModel({name: 'Session', scope: 'auth', collection: 'sessions'});
+const db = createCouchsetClient({bucketName: 'app', models: [sessions]});
+const sessionModel = db.model(sessions); // registers and binds; no DDL
+```
+
+Read the [full client and model-definition guide](./docs/next-primitives.md#couchset-next-primitives).
+
+### Provisioning and dynamic models
+
+```ts
+await db.ensureCollections(); // creates only missing scopes and collections
+await db.ensureIndexes();     // create-only index DDL
+
+const reports = await db.registerModel(reportDefinition, {provision: {collections: true}});
+```
+
+Read about [provisioning and dynamic models](./docs/next-primitives.md#provisioning-and-dynamic-models).
+
+### Transactions and CAS
+
+```ts
+await db.transaction(async (tx) => {
+    await tx.model(sessions).insert({id: 'session::1', userId: 'user::1'});
+});
+
+const outcome = await sessionModel.consumeOnce('session::1', knownCas);
+```
+
+Read the [transaction and CAS safety notes](./docs/next-primitives.md#transactions-and-cas).
+
+### Safe index plans
+
+```ts
+const plan = await db.planIndexes(); // inspect missing, matching, and drifted indexes
+await db.applyIndexPlan(plan);        // creates safe replacements and waits for them
+```
+
+Read about [index drift and opt-in cleanup](./docs/next-primitives.md#index-drift).
+
+### Eventing functions
+
+```ts
+import {defineEventingFunction} from 'couchset/next';
+
+const auditOrders = defineEventingFunction({
+    name: 'audit_orders',
+    code: 'function OnUpdate(doc, meta) { log(meta.id); }',
+    sourceKeyspace: {bucket: 'app', scope: 'sales', collection: 'orders'},
+});
+
+const eventing = db.eventing({
+    namespace: 'billing',
+    metadataKeyspace: {bucket: 'app', scope: 'eventing', collection: 'billing_metadata'},
+    definitions: [auditOrders],
+});
+
+await eventing.apply();
+```
+
+Read the [Eventing lifecycle and safety guide](./docs/next-primitives.md#eventing-functions).
+
+### Test fixtures
+
+```ts
+import {createCouchsetTestFixture} from 'couchset/next';
+
+const {model, cleanup} = await createCouchsetTestFixture(db, {name: 'Invoice'});
+// use model in the test
+await cleanup();
+```
+
+Read about [isolated CouchSet test fixtures](./docs/next-primitives.md#tests).
+
 ## Connection Lifecycle
 
 Models can be declared before connecting. Model operations wait for the shared connection before binding to the Couchbase bucket and collection.

package/dist/eventing.d.ts

@@ -0,0 +1,179 @@
+import type { EventingFunction, EventingFunctionManager, EventingFunctionSettings, EventingFunctionState } from 'couchbase';
+/** A Couchbase bucket/scope/collection used by an Eventing function. */
+export interface EventingKeyspace {
+    bucket: string;
+    scope?: string;
+    collection?: string;
+}
+/**
+ * A declarative Eventing handler. `name` is logical: CouchSet derives the
+ * physical Couchbase name from the Eventing namespace.
+ */
+export interface EventingDefinition {
+    name: string;
+    code: string;
+    sourceKeyspace: EventingKeyspace;
+    enforceSchema?: boolean;
+    bucketBindings?: EventingFunction['bucketBindings'];
+    urlBindings?: EventingFunction['urlBindings'];
+    constantBindings?: EventingFunction['constantBindings'];
+    settings?: Partial<EventingFunctionSettings>;
+}
+export type EventingFunctionDefinition = EventingDefinition;
+/**
+ * The metadata collection is used only by Couchbase Eventing for checkpoints
+ * and timers. CouchSet never opens it as an application collection or writes
+ * documents to it.
+ */
+export interface EventingOptions {
+    /** Required ownership boundary for physical Couchbase function names. */
+    namespace: string;
+    /** A dedicated collection reserved for Couchbase Eventing metadata. */
+    metadataKeyspace: EventingKeyspace;
+    /** Definitions registered when the control plane is constructed. */
+    definitions?: EventingDefinition[];
+    /** Alias for definitions, useful for manifest-shaped configuration. */
+    functions?: EventingDefinition[];
+    /** Explicit SDK manager injection, primarily for tests or owned clusters. */
+    manager?: EventingFunctionManagerLike;
+    /** Maximum time to wait for Couchbase Eventing lifecycle convergence. */
+    lifecycleTimeoutMs?: number;
+    /** Delay between lifecycle status checks. Defaults to 250ms. */
+    lifecyclePollIntervalMs?: number;
+}
+export interface EventingApplyOptions {
+    /**
+     * Permit source or metadata keyspace changes. Couchbase must undeploy first,
+     * which erases the function's timers and checkpoints.
+     */
+    allowRecreate?: boolean;
+}
+export type EventingOutcomeAction = 'created' | 'updated' | 'resumed' | 'unchanged' | 'pruned' | 'paused' | 'removed' | 'requires-recreate';
+export interface EventingOutcome {
+    action: EventingOutcomeAction;
+    /** Lifecycle operations performed for this function, in order. */
+    actions: EventingOutcomeAction[];
+    name: string;
+    physicalName: string;
+    /** Present whenever undeploying can erase Eventing timers/checkpoints. */
+    timerStateLost?: boolean;
+    message?: string;
+}
+/**
+ * Each status array contains the matching outcome, so callers can inspect a
+ * report directly without parsing text. An update can also be in `paused` and
+ * `resumed`, because that is the safe lifecycle used to perform the update.
+ */
+export interface EventingReport {
+    outcomes: EventingOutcome[];
+    created: EventingOutcome[];
+    updated: EventingOutcome[];
+    resumed: EventingOutcome[];
+    unchanged: EventingOutcome[];
+    pruned: EventingOutcome[];
+    paused: EventingOutcome[];
+    removed: EventingOutcome[];
+    requiresRecreate: EventingOutcome[];
+}
+/** The portion of SDK 4.7's EventingFunctionManager used by CouchSet. */
+export interface EventingFunctionManagerLike {
+    upsertFunction(functionDefinition: EventingFunction): Promise<void>;
+    dropFunction(name: string): Promise<void>;
+    getAllFunctions(): Promise<EventingFunction[]>;
+    deployFunction(name: string): Promise<void>;
+    undeployFunction(name: string): Promise<void>;
+    pauseFunction(name: string): Promise<void>;
+    resumeFunction(name: string): Promise<void>;
+    functionsStatus(): Promise<{
+        functions: EventingFunctionState[];
+    }>;
+}
+/** A minimal client shape that lets Eventing acquire the connected SDK cluster. */
+export interface EventingClient {
+    ready(): Promise<any>;
+    getConnection(): {
+        cluster: {
+            eventingFunctions?: () => EventingFunctionManager;
+        };
+    };
+}
+/**
+ * Declarative Eventing reconciler backed by the SDK 4.7 EventingFunctionManager.
+ * It only manages names starting with its namespace prefix.
+ */
+export declare class Eventing {
+    private readonly definitionsByName;
+    private readonly eventingMetadataKeyspace;
+    private readonly lifecyclePollIntervalMs;
+    private readonly lifecycleTimeoutMs;
+    private readonly prefix;
+    private readonly client?;
+    private readonly explicitManager?;
+    constructor(client: EventingClient | undefined, options: EventingOptions);
+    /** Logical namespace that owns this controller's physical functions. */
+    get namespace(): string;
+    /** A copy of registered, code-only declarations. This performs no I/O. */
+    definitions(): EventingDefinition[];
+    /** Converts a logical declaration name into its Couchbase function name. */
+    physicalName(name: string): string;
+    /** Registers or replaces an in-memory manifest declaration without I/O. */
+    register(definition: EventingDefinition): EventingDefinition;
+    /** Alias for register(), matching the declaration-oriented API vocabulary. */
+    define(definition: EventingDefinition): EventingDefinition;
+    apply(options?: EventingApplyOptions): Promise<EventingReport>;
+    apply(definition: EventingDefinition, options?: EventingApplyOptions): Promise<EventingReport>;
+    /** Temporarily disables one namespace-owned Eventing function. */
+    pause(name: string): Promise<EventingReport>;
+    /**
+     * Intentionally undeploys then deletes one namespace-owned function.
+     * Undeployment erases Couchbase Eventing timers and checkpoints.
+     */
+    remove(name: string): Promise<EventingReport>;
+    private reconcile;
+    private prune;
+    private matches;
+    private sdkDefinition;
+    private metadataKeyspace;
+    private manager;
+    private states;
+    /**
+     * Management requests acknowledge receipt, not necessarily completion. Do
+     * not issue the next incompatible Eventing operation until status confirms
+     * that Couchbase has converged.
+     */
+    private waitForLifecycle;
+    /**
+     * Couchbase Server may turn a paused function into an undeployed function
+     * when upsert persists new code/settings/bindings. Inspect that post-upsert
+     * state rather than assuming resume is legal; deploy is the compatible
+     * activation operation in that case.
+     */
+    private activateAfterUpsert;
+    /**
+     * A live function with no status row is unknown, not safely undeployed.
+     * Poll for a positive row; a known transitional row remains an immediate
+     * blocker so callers do not race an operator's in-progress lifecycle call.
+     */
+    private stableLifecycle;
+    /** Waits for a stable state caused by this controller's own upsert call. */
+    private waitForStableLifecycle;
+    private record;
+    private outcome;
+    private owns;
+    private logicalName;
+    private assertDefinition;
+    private assertLogicalName;
+    private assertStable;
+    private isDefinition;
+    private positiveNumber;
+    private nonNegativeNumber;
+}
+/**
+ * Construct an Eventing control plane from a CouchSet client. The client is
+ * used only to obtain the SDK EventingFunctionManager after `ready()`.
+ */
+export declare const createEventing: (client: EventingClient, options: EventingOptions) => Eventing;
+/** Construct an Eventing control plane around an application-owned SDK manager. */
+export declare const createEventingWithManager: (options: EventingOptions) => Eventing;
+/** A small helper that makes Eventing definitions read as manifest declarations. */
+export declare const defineEventingFunction: (definition: EventingDefinition) => EventingDefinition;