@dbos-inc/dbos-sdk 2.7.27-preview → 2.7.34

package/dist/src/dbos.js

@@ -71,6 +71,11 @@ class DBOS {
                 : dbos_executor_1.DebugMode.ENABLED
             : dbos_executor_1.DebugMode.DISABLED;
     }
+    /**
+     * Set configuration of `DBOS` prior to `launch`
+     * @param config - configuration of services needed by DBOS
+     * @param runtimeConfig - configuration of runtime access to DBOS
+     */
     static setConfig(config, runtimeConfig) {
         DBOS.dbosConfig = config;
         DBOS.runtimeConfig = runtimeConfig;
@@ -85,13 +90,20 @@ class DBOS {
             }
         }
     }
-    // For unit testing purposes only
+    /**
+     * @deprecated For unit testing purposes only
+     *   Use `setConfig`
+     */
     static setAppConfig(key, newValue) {
         const conf = DBOS.dbosConfig?.application;
         if (!conf)
             throw new error_1.DBOSExecutorNotInitializedError();
         (0, lodash_1.set)(conf, key, newValue);
     }
+    /**
+     * Drop DBOS system database.
+     * USE IN TESTS ONLY - ALL WORKFLOWS, QUEUES, ETC. WILL BE LOST.
+     */
     static async dropSystemDB() {
         if (!DBOS.dbosConfig) {
             DBOS.dbosConfig = (0, config_1.parseConfigFile)()[0];
@@ -99,11 +111,17 @@ class DBOS {
         DBOS.translateConfig();
         return system_database_1.PostgresSystemDatabase.dropSystemDB(DBOS.dbosConfig);
     }
-    /** Only relevant for TypeORM, and for testing purposes only, not production */
+    /**
+     * Use ORMEntities to set up database schema.
+     * Only relevant for TypeORM, and for testing purposes only, not production
+     */
     static async createUserSchema() {
         return dbos_executor_1.DBOSExecutor.globalInstance?.userDatabase.createSchema();
     }
-    /** Only relevant for TypeORM, and for testing purposes only, not production */
+    /**
+     * Use ORMEntities to drop database schema.
+     * Only relevant for TypeORM, and for testing purposes only, not production
+     */
     static async dropUserSchema() {
         return dbos_executor_1.DBOSExecutor.globalInstance?.userDatabase.dropSchema();
     }
@@ -111,9 +129,20 @@ class DBOS {
     static async loadClasses(dbosEntrypointFiles) {
         return await runtime_1.DBOSRuntime.loadClasses(dbosEntrypointFiles);
     }
+    /**
+     * Check if DBOS has been `launch`ed (and not `shutdown`)
+     * @returns `true` if DBOS has been launched, or `false` otherwise
+     */
+    static isInitialized() {
+        return !!dbos_executor_1.DBOSExecutor.globalInstance;
+    }
+    /**
+     * Launch DBOS, starting recovery and request handling
+     * @param options - Launch options for connecting to DBOS Conductor
+     */
     static async launch(options) {
         // Do nothing is DBOS is already initialized
-        if (dbos_executor_1.DBOSExecutor.globalInstance)
+        if (DBOS.isInitialized())
             return;
         const debugMode = options?.debugMode ?? DBOS.getDebugModeFromEnv();
         const isDebugging = debugMode !== dbos_executor_1.DebugMode.DISABLED;
@@ -211,6 +240,13 @@ class DBOS {
         }
         (0, decorators_1.recordDBOSLaunch)();
     }
+    /**
+     * Logs all workflows that can be invoked externally, rather than directly by the applicaton.
+     * This includes:
+     *   All DBOS event receiver entrypoints (message queues, URLs, etc.)
+     *   Scheduled workflows
+     *   Queues
+     */
     static logRegisteredEndpoints() {
         if (!dbos_executor_1.DBOSExecutor.globalInstance)
             return;
@@ -221,6 +257,12 @@ class DBOS {
             evtRcvr.logRegisteredEndpoints();
         }
     }
+    /**
+     * Shut down DBOS processing:
+     *   Stops receiving external workflow requests
+     *   Disconnects from administration / Conductor
+     *   Stops workflow processing and disconnects from databases
+     */
     static async shutdown() {
         // Stop the app server
         if (DBOS.appServer) {
@@ -253,18 +295,28 @@ class DBOS {
         utils_1.globalParams.executorID = process.env.DBOS__VMID || 'local';
         (0, decorators_1.recordDBOSShutdown)();
     }
+    /** Stop listening for external events (for testing) */
     static async deactivateEventReceivers() {
         return dbos_executor_1.DBOSExecutor.globalInstance?.deactivateEventReceivers();
     }
+    /** Start listening for external events (for testing) */
     static async initEventReceivers() {
         return dbos_executor_1.DBOSExecutor.globalInstance?.initEventReceivers();
     }
+    /**
+     * Global DBOS executor instance
+     */
     static get executor() {
         if (!dbos_executor_1.DBOSExecutor.globalInstance) {
             throw new error_1.DBOSExecutorNotInitializedError();
         }
         return dbos_executor_1.DBOSExecutor.globalInstance;
     }
+    /**
+     * Creates a node.js HTTP handler for all entrypoints registered with `@DBOS.getApi`
+     * and other decorators.  The handler can be retrieved with `DBOS.getHTTPHandlersCallback()`.
+     * This method does not start listening for requests.  For that, call `DBOS.launchAppHTTPServer()`.
+     */
     static setUpHandlerCallback() {
         if (!dbos_executor_1.DBOSExecutor.globalInstance) {
             throw new error_1.DBOSExecutorNotInitializedError();
@@ -274,6 +326,11 @@ class DBOS {
         const server = new server_1.DBOSHttpServer(dbos_executor_1.DBOSExecutor.globalInstance);
         return server;
     }
+    /**
+     * Creates a node.js HTTP handler for all entrypoints registered with `@DBOS.getApi`
+     * and other decorators.  This method also starts listening for requests, on the port
+     * specified in the `DBOSRuntimeConfig`.
+     */
     static async launchAppHTTPServer() {
         const server = DBOS.setUpHandlerCallback();
         if (DBOS.runtimeConfig) {
@@ -281,16 +338,19 @@ class DBOS {
             DBOS.appServer = await server.appListen(DBOS.runtimeConfig.port);
         }
     }
-    // This retrieves the HTTP handlers callback for DBOS HTTP.
-    //  (This is the one that handles the @DBOS.getApi, etc., methods.)
-    // Useful for testing purposes, or to combine the DBOS service with routes.
-    // If you are using your own HTTP server, this won't return anything.
+    /**
+     * Retrieves the HTTP handlers callback for DBOS HTTP.
+     *  (This is the one that handles the @DBOS.getApi, etc., methods.)
+     *   Useful for testing purposes, or to combine the DBOS service with other
+     *   node.js HTTP server frameworks.
+     */
     static getHTTPHandlersCallback() {
         if (!server_1.DBOSHttpServer.instance) {
             return undefined;
         }
         return server_1.DBOSHttpServer.instance.app.callback();
     }
+    /** For unit testing of admin server (do not call) */
     static getAdminCallback() {
         if (!server_1.DBOSHttpServer.instance) {
             return undefined;
@@ -307,6 +367,7 @@ class DBOS {
     //////
     // Context
     //////
+    /** Get the current DBOS Logger, appropriate to the current context */
     static get logger() {
         const ctx = (0, context_1.getCurrentDBOSContext)();
         if (ctx)
@@ -316,33 +377,40 @@ class DBOS {
             return executor.logger;
         return new logs_1.GlobalLogger();
     }
+    /** Get the current DBOS tracing span, appropriate to the current context */
     static get span() {
         const ctx = (0, context_1.getCurrentDBOSContext)();
         if (ctx)
             return ctx.span;
         return undefined;
     }
+    /** Get the current HTTP request (within `@DBOS.getApi` et al) */
     static getRequest() {
         return (0, context_1.getCurrentDBOSContext)()?.request;
     }
+    /** Get the current HTTP request (within `@DBOS.getApi` et al) */
     static get request() {
         const r = DBOS.getRequest();
         if (!r)
             throw new error_1.DBOSError('`DBOS.request` accessed from outside of HTTP requests');
         return r;
     }
+    /** Get the current Koa context (within `@DBOS.getApi` et al) */
     static getKoaContext() {
         return (0, context_1.getCurrentDBOSContext)()?.koaContext;
     }
+    /** Get the current Koa context (within `@DBOS.getApi` et al) */
     static get koaContext() {
         const r = DBOS.getKoaContext();
         if (!r)
             throw new error_1.DBOSError('`DBOS.koaContext` accessed from outside koa request');
         return r;
     }
+    /** Get the current workflow ID */
     static get workflowID() {
         return (0, context_1.getCurrentDBOSContext)()?.workflowUUID;
     }
+    /** Get the current step number, within the current workflow */
     static get stepID() {
         if (DBOS.isInStep()) {
             return (0, context_1.getCurrentContextStore)()?.curStepFunctionId;
@@ -357,37 +425,57 @@ class DBOS {
     static get stepStatus() {
         return (0, context_1.getCurrentContextStore)()?.stepStatus;
     }
+    /** Get the current authenticated user */
     static get authenticatedUser() {
         return (0, context_1.getCurrentDBOSContext)()?.authenticatedUser ?? '';
     }
+    /** Get the roles granted to the current authenticated user */
     static get authenticatedRoles() {
         return (0, context_1.getCurrentDBOSContext)()?.authenticatedRoles ?? [];
     }
+    /** Get the role assumed by the current user giving authorization to execute the current function */
     static get assumedRole() {
         return (0, context_1.getCurrentDBOSContext)()?.assumedRole ?? '';
     }
+    /** @returns true if called from within a transaction, false otherwise */
     static isInTransaction() {
         return (0, context_1.getCurrentContextStore)()?.curTxFunctionId !== undefined;
     }
+    /** @returns true if called from within a stored procedure, false otherwise */
     static isInStoredProc() {
         return (0, context_1.getCurrentContextStore)()?.isInStoredProc ?? false;
     }
+    /** @returns true if called from within a step, false otherwise */
     static isInStep() {
         return (0, context_1.getCurrentContextStore)()?.curStepFunctionId !== undefined;
     }
+    /**
+     * @returns true if called from within a workflow
+     *  (regardless of whether the workflow is currently executing a step,
+     *   transaction, or procedure), false otherwise
+     */
     static isWithinWorkflow() {
         return (0, context_1.getCurrentContextStore)()?.workflowId !== undefined;
     }
+    /**
+     * @returns true if called from within a workflow that is not currently executing
+     *  a step, transaction, or procedure, or false otherwise
+     */
     static isInWorkflow() {
-        return DBOS.isWithinWorkflow() && !DBOS.isInTransaction() && !DBOS.isInStep();
+        return DBOS.isWithinWorkflow() && !DBOS.isInTransaction() && !DBOS.isInStep() && !DBOS.isInStoredProc();
     }
     // sql session (various forms)
+    /** @returns the current SQL client; only allowed within `@DBOS.transaction` functions */
     static get sqlClient() {
         if (!DBOS.isInTransaction())
             throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid use of `DBOS.sqlClient` outside of a `transaction`');
         const ctx = (0, context_1.assertCurrentDBOSContext)();
         return ctx.client;
     }
+    /**
+     * @returns the current PG SQL client;
+     *  only allowed within `@DBOS.transaction` functions when a `PGNODE` user database is in use
+     */
     static get pgClient() {
         const client = DBOS.sqlClient;
         if (!DBOS.isInStoredProc() && DBOS.dbosConfig?.userDbclient !== user_database_1.UserDatabaseName.PGNODE) {
@@ -395,6 +483,10 @@ class DBOS {
         }
         return client;
     }
+    /**
+     * @returns the current Knex SQL client;
+     *  only allowed within `@DBOS.transaction` functions when a `KNEX` user database is in use
+     */
     static get knexClient() {
         if (DBOS.isInStoredProc()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError(`Requested 'DBOS.knexClient' from within a stored procedure`);
@@ -405,6 +497,10 @@ class DBOS {
         const client = DBOS.sqlClient;
         return client;
     }
+    /**
+     * @returns the current Prisma SQL client;
+     *  only allowed within `@DBOS.transaction` functions when a `PRISMA` user database is in use
+     */
     static get prismaClient() {
         if (DBOS.isInStoredProc()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError(`Requested 'DBOS.prismaClient' from within a stored procedure`);
@@ -415,6 +511,10 @@ class DBOS {
         const client = DBOS.sqlClient;
         return client;
     }
+    /**
+     * @returns the current  TypeORM SQL client;
+     *  only allowed within `@DBOS.transaction` functions when the `TYPEORM` user database is in use
+     */
     static get typeORMClient() {
         if (DBOS.isInStoredProc()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError(`Requested 'DBOS.typeORMClient' from within a stored procedure`);
@@ -425,6 +525,10 @@ class DBOS {
         const client = DBOS.sqlClient;
         return client;
     }
+    /**
+     * @returns the current Drizzle SQL client;
+     *  only allowed within `@DBOS.transaction` functions when the `DRIZZLE` user database is in use
+     */
     static get drizzleClient() {
         if (DBOS.isInStoredProc()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError(`Requested 'DBOS.drizzleClient' from within a stored procedure`);
@@ -435,6 +539,12 @@ class DBOS {
         const client = DBOS.sqlClient;
         return client;
     }
+    /**
+     * Gets configuration information from the `application` section
+     *  of `DBOSConfig`
+     * @param key - name of configuration item
+     * @param defaultValue - value to return if `key` does not exist in the configuration
+     */
     static getConfig(key, defaultValue) {
         const ctx = (0, context_1.getCurrentDBOSContext)();
         if (ctx && defaultValue)
@@ -445,6 +555,13 @@ class DBOS {
             return DBOS.executor.getConfig(key, defaultValue);
         return defaultValue;
     }
+    /**
+     * Query the current application database
+     * @param sql - parameterized SQL statement (string) to execute
+     * @param params - parameter values for `sql`
+     * @template T - Type for the returned records
+     * @returns Array of records returned by the SQL statement
+     */
     static async queryUserDB(sql, params) {
         if (DBOS.isWithinWorkflow() && !DBOS.isInStep()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `queryUserDB` inside a `workflow`, without being in a `step`');
@@ -454,12 +571,24 @@ class DBOS {
     //////
     // Workflow and other operations
     //////
+    /**
+     * Get the workflow status given a workflow ID
+     * @param workflowID - ID of the workflow
+     * @returns status of the workflow as `WorkflowStatus`, or `null` if there is no workflow with `workflowID`
+     */
     static getWorkflowStatus(workflowID) {
         if (DBOS.isWithinWorkflow() && !DBOS.isInStep()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `getWorkflowStatus` inside a `workflow`, without being in a `step`');
         }
         return DBOS.executor.getWorkflowStatus(workflowID);
     }
+    /**
+     * Create a workflow handle with a given workflow ID.
+     * This call always returns a handle, even if the workflow does not exist.
+     * The resulting handle will check the database to provide any workflow information.
+     * @param workflowID - ID of the workflow
+     * @returns `WorkflowHandle` that can be used to poll for the status or result of any workflow with `workflowID`
+     */
     static retrieveWorkflow(workflowID) {
         if (DBOS.isWithinWorkflow()) {
             if (!DBOS.isInWorkflow()) {
@@ -469,25 +598,51 @@ class DBOS {
         }
         return DBOS.executor.retrieveWorkflow(workflowID);
     }
+    /**
+     * Query the system database for all workflows matching the provided predicate
+     * @param input - `GetWorkflowsInput` predicate for filtering returned workflows
+     * @returns `GetWorkflowsOutput` listing the workflow IDs of matching workflows
+     */
     static async getWorkflows(input) {
         if (DBOS.isWithinWorkflow() && !DBOS.isInStep()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `getWorkflows` inside a `workflow`, without being in a `step`');
         }
         return await DBOS.executor.getWorkflows(input);
     }
-    static async cancelWorkflow(wfid) {
-        await DBOS.executor.cancelWorkflow(wfid);
+    /**
+     * Cancel a workflow given its ID.
+     * If the workflow is currently running, `DBOSWorkflowCancelledError` will be
+     *   thrown from its next DBOS call.
+     * @param workflowID - ID of the workflow
+     */
+    static async cancelWorkflow(workflowID) {
+        await DBOS.executor.cancelWorkflow(workflowID);
     }
-    static async resumeWorkflow(wfid) {
-        return await DBOS.executor.resumeWorkflow(wfid);
+    /**
+     * Resume a workflow given its ID.
+     * @param workflowID - ID of the workflow
+     */
+    static async resumeWorkflow(workflowID) {
+        return await DBOS.executor.resumeWorkflow(workflowID);
     }
+    /**
+     * Retrieve the contents of a workflow queue.
+     * @param input - Filter predicate, containing the queue name and other criteria
+     */
     static async getWorkflowQueue(input) {
         if (DBOS.isWithinWorkflow() && !DBOS.isInStep()) {
             throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `getWorkflows` inside a `workflow`, without being in a `step`');
         }
         return await DBOS.executor.getWorkflowQueue(input);
     }
-    // durable sleep when called from within workflows
+    /**
+     * Sleep for the specified amount of time.
+     * If called from within a workflow, the sleep is "durable",
+     *   meaning that the workflow will sleep until the wakeup time
+     *   (calculated by adding `durationMS` to the original invocation time),
+     *   regardless of workflow recovery.
+     * @param durationMS - Length of sleep, in milliseconds.
+     */
     static async sleepms(durationMS) {
         if (DBOS.isWithinWorkflow() && !DBOS.isInStep()) {
             if (DBOS.isInTransaction()) {
@@ -497,18 +652,27 @@ class DBOS {
         }
         await (0, utils_1.sleepms)(durationMS);
     }
+    /** @see sleepms */
     static async sleepSeconds(durationSec) {
         return DBOS.sleepms(durationSec * 1000);
     }
+    /** @see sleepms */
     static async sleep(durationMS) {
         return DBOS.sleepms(durationMS);
     }
-    static async withNextWorkflowID(wfid, callback) {
+    /**
+     * Use the provided `workflowID` as the identifier for first workflow started
+     *   within the `callback` function.
+     * @param workflowID - ID to assign to the first workflow started
+     * @param callback - Function to run, which would start a workflow
+     * @returns - Return value from `callback`
+     */
+    static async withNextWorkflowID(workflowID, callback) {
         const pctx = (0, context_1.getCurrentContextStore)();
         if (pctx) {
             const pcwfid = pctx.idAssignedForNextWorkflow;
             try {
-                pctx.idAssignedForNextWorkflow = wfid;
+                pctx.idAssignedForNextWorkflow = workflowID;
                 return callback();
             }
             finally {
@@ -516,9 +680,18 @@ class DBOS {
             }
         }
         else {
-            return (0, context_1.runWithTopContext)({ idAssignedForNextWorkflow: wfid }, callback);
+            return (0, context_1.runWithTopContext)({ idAssignedForNextWorkflow: workflowID }, callback);
         }
     }
+    /**
+     * Use the provided `callerName`, `span`, and `request` as context for any
+     *   DBOS functions called within the `callback` function.
+     * @param callerName - Tracing caller name
+     * @param span - Tracing span
+     * @param request - HTTP request that initiated the call
+     * @param callback - Function to run with tracing context in place
+     * @returns - Return value from `callback`
+     */
     static async withTracedContext(callerName, span, request, callback) {
         const pctx = (0, context_1.getCurrentContextStore)();
         if (pctx) {
@@ -531,6 +704,15 @@ class DBOS {
             return (0, context_1.runWithTopContext)({ span, request }, callback);
         }
     }
+    /**
+     * Use the provided `authedUser` and `authedRoles` as the authenticated user for
+     *   any security checks or calls to `DBOS.authenticatedUser`
+     *   or `DBOS.authenticatedRoles` placed within the `callback` function.
+     * @param authedUser - Authenticated user
+     * @param authedRoles - Authenticated roles
+     * @param callback - Function to run with authentication context in place
+     * @returns - Return value from `callback`
+     */
     static async withAuthedContext(authedUser, authedRoles, callback) {
         const pctx = (0, context_1.getCurrentContextStore)();
         if (pctx) {
@@ -542,7 +724,13 @@ class DBOS {
             return (0, context_1.runWithTopContext)({ authenticatedUser: authedUser, authenticatedRoles: authedRoles }, callback);
         }
     }
-    // This generic setter helps users calling DBOS operation to pass a name, later used in seeding a parent OTel span for the operation.
+    /**
+     * This generic setter helps users calling DBOS operation to pass a name,
+     *   later used in seeding a parent OTel span for the operation.
+     * @param callerName - Tracing caller name
+     * @param callback - Function to run with tracing context in place
+     * @returns - Return value from `callback`
+     */
     static async withNamedContext(callerName, callback) {
         const pctx = (0, context_1.getCurrentContextStore)();
         if (pctx) {
@@ -553,12 +741,18 @@ class DBOS {
             return (0, context_1.runWithTopContext)({ operationCaller: callerName }, callback);
         }
     }
-    static async withWorkflowQueue(wfq, callback) {
+    /**
+     * Use queue named `queueName` for any workflows started within the `callback`.
+     * @param queueName - Name of queue upon which qll workflows called or started within `callback` will be run
+     * @param callback - Function to run, which would call or start workflows
+     * @returns - Return value from `callback`
+     */
+    static async withWorkflowQueue(queueName, callback) {
         const pctx = (0, context_1.getCurrentContextStore)();
         if (pctx) {
             const pcwfq = pctx.queueAssignedForWorkflows;
             try {
-                pctx.queueAssignedForWorkflows = wfq;
+                pctx.queueAssignedForWorkflows = queueName;
                 return callback();
             }
             finally {
@@ -566,7 +760,7 @@ class DBOS {
             }
         }
         else {
-            return (0, context_1.runWithTopContext)({ queueAssignedForWorkflows: wfq }, callback);
+            return (0, context_1.runWithTopContext)({ queueAssignedForWorkflows: queueName }, callback);
         }
     }
     static startWorkflow(target, params) {
@@ -766,6 +960,17 @@ class DBOS {
             return proxy;
         }
     }
+    /**
+     * Send `message` on optional `topic` to the workflow with `destinationID`
+     *  This can be done from inside or outside of DBOS workflow functions
+     *  Use the optional `idempotencyKey` to guarantee that the message is sent exactly once
+     * @see `DBOS.recv`
+     *
+     * @param destinationID - ID of the workflow that will `recv` the message
+     * @param message - Message to send, which must be serializable as JSON
+     * @param topic - Optional topic; if specified the `recv` command can specify the same topic to receive selectively
+     * @param idempotencyKey - Optional key for sending the message exactly once
+     */
     static async send(destinationID, message, topic, idempotencyKey) {
         if (DBOS.isWithinWorkflow()) {
             if (!DBOS.isInWorkflow()) {
@@ -778,6 +983,18 @@ class DBOS {
         }
         return DBOS.executor.send(destinationID, message, topic, idempotencyKey);
     }
+    /**
+     * Receive a message on optional `topic` from within a workflow.
+     *  This must be called from within a workflow; this workflow's ID is used to check for messages sent by `DBOS.send`
+     *  This can be configured to time out.
+     *  Messages are received in the order in which they are sent (per-sender / causal order).
+     * @see `DBOS.send`
+     *
+     * @param topic - Optional topic; if specified the `recv` command can specify the same topic to receive selectively
+     * @param timeoutSeconds - Optional timeout; if no message is received before the timeout, `null` will be returned
+     * @template T - The type of message that is expected to be received
+     * @returns Any message received, or `null` if the timeout expires
+     */
     static async recv(topic, timeoutSeconds) {
         if (DBOS.isWithinWorkflow()) {
             if (!DBOS.isInWorkflow()) {
@@ -787,6 +1004,15 @@ class DBOS {
         }
         throw new error_1.DBOSInvalidWorkflowTransitionError('Attempt to call `DBOS.recv` outside of a workflow'); // Only workflows can recv
     }
+    /**
+     * Set an event, from within a DBOS workflow.  This value can be retrieved with `DBOS.getEvent`.
+     * If the event `key` already exists, its `value` is updated.
+     * This function can only be called from within a workflow.
+     * @see `DBOS.getEvent`
+     *
+     * @param key - The key for the event; at most one value is associated with a key at any given time.
+     * @param value - The value to associate with `key`
+     */
     static async setEvent(key, value) {
         if (DBOS.isWithinWorkflow()) {
             if (!DBOS.isInWorkflow()) {
@@ -796,6 +1022,18 @@ class DBOS {
         }
         throw new error_1.DBOSInvalidWorkflowTransitionError('Attempt to call `DBOS.setEvent` outside of a workflow'); // Only workflows can set event
     }
+    /**
+     * Get the value of a workflow event, or wait for it to be set.
+     * This function can be called inside or outside of DBOS workflow functions.
+     * If this function is called from within a workflow, its result is durably checkpointed.
+     * @see `DBOS.setEvent`
+     *
+     * @param workflowID - The ID of the workflow with the corresponding `setEvent`
+     * @param key - The key for the event; at most one value is associated with a key at any given time.
+     * @param timeoutSeconds - Optional timeout; if a value for `key` is not set before the timeout, `null` will be returned
+     * @template T - The expected type for the value assigned to `key`
+     * @returns The value to associate with `key`, or `null` if the timeout is hit
+     */
     static async getEvent(workflowID, key, timeoutSeconds) {
         if (DBOS.isWithinWorkflow()) {
             if (!DBOS.isInWorkflow()) {
@@ -808,6 +1046,10 @@ class DBOS {
     //////
     // Decorators
     //////
+    /**
+     * Decorator associating a class static method with an invocation schedule
+     * @param schedulerConfig - The schedule, consisting of a crontab and policy for "make-up work"
+     */
     static scheduled(schedulerConfig) {
         function scheddec(target, propertyKey, inDescriptor) {
             const { descriptor, registration } = (0, decorators_1.registerAndWrapDBOSFunction)(target, propertyKey, inDescriptor);
@@ -817,6 +1059,12 @@ class DBOS {
         }
         return scheddec;
     }
+    /**
+     * Decorator designating a method as a DBOS workflow
+     *   Durable execution will be applied within calls to the workflow function
+     *   This also registers the function so that it is available during recovery
+     * @param config - Configuration information for the workflow
+     */
     static workflow(config = {}) {
         function decorator(target, propertyKey, inDescriptor) {
             const { descriptor, registration } = (0, decorators_1.registerAndWrapDBOSFunction)(target, propertyKey, inDescriptor);
@@ -894,6 +1142,12 @@ class DBOS {
         }
         return decorator;
     }
+    /**
+     * Decorator designating a method as a DBOS transaction, making SQL clients available.
+     *   A durable execution checkpoint will be applied to to the underlying database transaction
+     * @see `DBOS.sqlClient`
+     * @param config - Configuration information for the transaction, particularly its isolation mode
+     */
     static transaction(config = {}) {
         function decorator(target, propertyKey, inDescriptor) {
             const { descriptor, registration } = (0, decorators_1.registerAndWrapDBOSFunction)(target, propertyKey, inDescriptor);
@@ -957,6 +1211,12 @@ class DBOS {
         }
         return decorator;
     }
+    /**
+     * Decorator designating a method as a DBOS stored procedure.
+     *   Within the procedure, `DBOS.sqlClient` is available for database operations.
+     *   A durable execution checkpoint will be applied to to the underlying database transaction
+     * @param config - Configuration information for the stored procedure, particularly its execution mode
+     */
     static storedProcedure(config = {}) {
         function decorator(target, propertyKey, inDescriptor) {
             const { descriptor, registration } = (0, decorators_1.registerAndWrapDBOSFunction)(target, propertyKey, inDescriptor);
@@ -1006,6 +1266,14 @@ class DBOS {
         }
         return decorator;
     }
+    /**
+     * Decorator designating a method as a DBOS step.
+     *   A durable checkpoint will be made after the step completes
+     *   This ensures "at least once" execution of the step, and that the step will not
+     *    be executed again once the checkpoint is recorded
+     *
+     * @param config - Configuration information for the step, particularly the retry policy
+     */
     static step(config = {}) {
         function decorator(target, propertyKey, inDescriptor) {
             const { descriptor, registration } = (0, decorators_1.registerAndWrapDBOSFunction)(target, propertyKey, inDescriptor);
@@ -1070,21 +1338,31 @@ class DBOS {
         }
         return decorator;
     }
+    /** Decorator indicating that the method is the target of HTTP GET operations for `url` */
     static getApi(url) {
         return httpApiDec(handlerTypes_1.APITypes.GET, url);
     }
+    /** Decorator indicating that the method is the target of HTTP POST operations for `url` */
     static postApi(url) {
         return httpApiDec(handlerTypes_1.APITypes.POST, url);
     }
+    /** Decorator indicating that the method is the target of HTTP PUT operations for `url` */
     static putApi(url) {
         return httpApiDec(handlerTypes_1.APITypes.PUT, url);
     }
+    /** Decorator indicating that the method is the target of HTTP PATCH operations for `url` */
     static patchApi(url) {
         return httpApiDec(handlerTypes_1.APITypes.PATCH, url);
     }
+    /** Decorator indicating that the method is the target of HTTP DELETE operations for `url` */
     static deleteApi(url) {
         return httpApiDec(handlerTypes_1.APITypes.DELETE, url);
     }
+    /**
+     * Decorate a class with the default list of required roles.
+     *   This class-level default can be overridden on a per-function basis with `requiredRole`.
+     * @param anyOf - The list of roles allowed access; authorization is granted if the authenticated user has any role on the list
+     */
     static defaultRequiredRole(anyOf) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         function clsdec(ctor) {
@@ -1093,6 +1371,11 @@ class DBOS {
         }
         return clsdec;
     }
+    /**
+     * Decorate a method with the default list of required roles.
+     * @see `DBOS.defaultRequiredRole`
+     * @param anyOf - The list of roles allowed access; authorization is granted if the authenticated user has any role on the list
+     */
     static requiredRole(anyOf) {
         function apidec(target, propertyKey, inDescriptor) {
             const { descriptor, registration } = (0, decorators_1.registerAndWrapDBOSFunction)(target, propertyKey, inDescriptor);
@@ -1107,20 +1390,23 @@ class DBOS {
     /**
      * Construct and register an object.
      * Calling this is not necessary; calling the constructor of any `ConfiguredInstance` subclass is sufficient
+     * @deprecated Use `new` directly
      */
     static configureInstance(cls, name, ...args) {
         return (0, decorators_1.configureInstance)(cls, name, ...args);
     }
-    // Function registration
+    // Function registration - for internal use
     static registerAndWrapDBOSFunction(target, propertyKey, descriptor) {
         return (0, decorators_1.registerAndWrapDBOSFunction)(target, propertyKey, descriptor);
     }
+    // For internal and testing purposes
     static async executeWorkflowById(workflowId, startNewWorkflow = false) {
         if (!dbos_executor_1.DBOSExecutor.globalInstance) {
             throw new error_1.DBOSExecutorNotInitializedError();
         }
         return dbos_executor_1.DBOSExecutor.globalInstance.executeWorkflowUUID(workflowId, startNewWorkflow);
     }
+    // For internal and testing purposes
     static async recoverPendingWorkflows(executorIDs = ['local']) {
         if (!dbos_executor_1.DBOSExecutor.globalInstance) {
             throw new error_1.DBOSExecutorNotInitializedError();
@@ -1129,6 +1415,7 @@ class DBOS {
     }
 }
 exports.DBOS = DBOS;
+/** @deprecated */
 class InitContext {
     createUserSchema() {
         DBOS.logger.warn('Schema synchronization is deprecated and unsafe for production use. Please use migrations instead: https://typeorm.io/migrations');