🔄 Common

Common documents cross-domain blocks, utility blocks, validators, and schemas that SDK services and custom route compositions reuse for normalization, access checks, pagination, and responses.

Start here

Import shared contracts from the SDK namespace that owns the export:

import {blocks, schemas, validators} from '@nodeblocks/backend-sdk';

const normalized = blocks.normalizeRawDocument({
  _id: 'database-id',
  id: 'public-id',
});

const requireAdmin = validators.checkIdentityType(['admin']);
const paginationParameters = schemas.paginationQueryParametersSchema;

normalizeRawDocument returns an infallible Result without MongoDB's _id; checkIdentityType returns a route validator; and paginationQueryParametersSchema is an array of reusable OpenAPI query parameters.

Common is not a mountable service and does not define features, handlers, or routes. Consumers import its public exports through blocks, schemas, and validators, then compose them into a domain service or custom route. Blocks provide errors, response normalization, redirects, and secure password generation. The first group is exported by blocks/common; redirect and password helpers are exported by blocks/utils. Schemas provide shared JSON Schema and OpenAPI definitions. Address-specific schemas are documented in Address. Validators authenticate, authorize, combine checks, and validate ownership. Validator factories receive configuration through the route payload. Authentication-aware validators use context.authenticate when supplied and otherwise fall back to Bearer-token authentication. Database-backed validators also require the named collection in context.db.

Common tasks

Task	Start with	Contract
Remove MongoDB _id before returning data	normalizeRawDocument	normalizeRawDocument or normalizeDocuments
Produce a consistent empty response body	normalizeEmptyBody	normalizeEmptyBody
Validate a notification timestamp anchor	assertHasCreatedAt	assertHasCreatedAt
Redirect an OAuth response	redirectTo	redirectTo
Generate an OAuth fallback password	generateRandomPassword	generateRandomPassword
Add standard page and limit query parameters	paginationQueryParametersSchema	paginationQueryParametersSchema
Require every or any access check	all or some	all or some
Restrict access by identity type or ownership	checkIdentityType, isSelf, or ownsResource	checkIdentityType, isSelf, or ownsResource

Reference map

Page	Purpose
Common blocks	Shared errors, normalizers, redirect behavior, and password generation.
Common schemas	Pagination, response, file, audit, and contact definitions.
Common validators	Authentication, identity type, ownership, and validator composition contracts.

Related modules

Authentication composes the shared authentication and authorization validators and uses empty-body normalization. OAuth consumes redirects and generated passwords during provider flows. Chat consumes shared pagination schemas, document normalization, and ownership composition. Product uses shared document normalizers and access validators for variant routes. Address owns address data schemas and postal-code lookup contracts. Backend types, schemas, and validators define the route payload and composition contracts these exports use.