🧱 Common blocks
Common blocks are reusable SDK operations and error types exported through blocks/common and blocks/utils from @nodeblocks/backend-sdk. CommonBlockError through assertHasCreatedAt come from blocks/common; redirectTo and generateRandomPassword are shared utility blocks from blocks/utils.
Inventory
| Export | Kind | Inputs | Result / behavior / errors |
|---|---|---|---|
CommonBlockError | Error class | Message, optional data | Base class for expected Common block failures. |
CommonUnexpectedBlockError | Error class | Message, optional data | Identifies an unexpected Common block failure; used by assertHasCreatedAt. |
normalizeEmptyBody | Function | None | Returns a new empty object directly and does not return a Result. |
normalizeRawDocument | Function | Record with optional _id | Returns Result<Record<string, unknown>, never> without _id. |
normalizeDocuments | Function | Array of records with optional _id | Returns an infallible combined Result containing normalized records. |
assertHasCreatedAt | Function | Record expected to contain createdAt | Returns ok(true) for a string value or CommonUnexpectedBlockError otherwise. |
redirectTo | Function | Express Response, URL, optional status | Calls response.redirect; defaults to status 302 and returns Result<void, Error>. |
generateRandomPassword | Function | Optional length | Returns a cryptographically random password; default length is 16. |
Details
CommonBlockError
Implementation
CommonBlockError extends the SDK BlockError without overriding its constructor. It accepts a message and optional unknown data, sets its runtime name to CommonBlockError, and carries no HTTP status code. Use it for an expected failure owned by a shared block; no current Common function constructs it directly.
CommonUnexpectedBlockError
Implementation
CommonUnexpectedBlockError extends BlockError, accepts a message and optional unknown data, and carries no HTTP status code. assertHasCreatedAt returns it with message Invalid createdAt. when the supplied record has no string createdAt.
normalizeEmptyBody
Implementation
Signature: normalizeEmptyBody(): object. It always returns {} directly, cannot fail, and is commonly placed before a 204 response terminator. It is consumed by Authentication, Organization, Product, and Notification route pipelines; see the Authentication routes, Organization routes, and Product routes.
normalizeRawDocument
Implementation
Signature: normalizeRawDocument(document: Record<string, unknown> & { _id?: string }): Result<Record<string, unknown>, never>. It removes only the top-level MongoDB _id, preserves every other field, and returns the remaining record in ok. It is used by Product variant and Profile response pipelines; see Product routes and Profile routes.
normalizeDocuments
Implementation
Signature: normalizeDocuments(documents: Record<string, unknown>[]): Result<Record<string, unknown>[], never>. It applies normalizeRawDocument to every record and combines the infallible results in input order. Consumers include Chat message-template routes, Product routes, Profile routes, and Notification routes.
assertHasCreatedAt
Implementation
Signature: assertHasCreatedAt(document: Record<string, unknown>): Result<boolean, Error>. It succeeds with true only when createdAt is a string. A missing or non-string value returns CommonUnexpectedBlockError with Invalid createdAt.. The Notification batch mark-as-read pipeline uses it to validate the latest-read anchor.
redirectTo
Implementation
Signature: redirectTo(response: Response, url: string, statusCode = 302): Result<void, Error>. It invokes Express response.redirect(statusCode, url) and wraps the returned value in ok; exceptions thrown by Express are not converted into an error Result. It terminates provider redirect flows in the OAuth routes.
generateRandomPassword
Implementation
Signature: generateRandomPassword(length = 16): string. It draws length bytes with Node.js crypto.randomBytes and maps them into uppercase letters, lowercase letters, digits, and the source-defined special-character set. Google, LINE, and Twitter OAuth account creation use it before hashing the fallback credential. A negative length is rejected by randomBytes; a zero length returns an empty string.