BuildX Common

A common utilities package for BuildX projects with a modular, domain-driven design architecture.

Installation

yarn add buildx-common

Optional Dependencies

Some features require additional dependencies to be installed:

ts-morph (Optional)

For AST-based TypeScript parsing functionality (used in collection type generation), install ts-morph:

yarn add ts-morph

If ts-morph is not installed, the AST-based functions will throw an error with a helpful message indicating that the dependency is required.

Functions that require ts-morph:

• generateSchemaFromTypeAST
• generateSchemasFromSourceAST
• generateSchemasFromTypesAST

Typegen parsing guarantees:

• Mixed relation unions prefer relation semantics:
  • BxText | Partial<Workflows> | BxDataObject -> DataObject (ref: workflows when ref mode applies)
  • (BxText | Partial<Workflows> | BxDataObject)[] -> DataObjects
• Embedded schema generation keeps nested object/list children explicit.
• Root-only _id / __bxstate are not injected into nested embedded object types.

Usage

Import Everything (Legacy Style)

import { z, ProjectSchema, UserSchema, FieldSchema } from 'buildx-common';

Import Specific Modules (Recommended)

// Import only validation utilities
import { zString, zNumber, zDate } from 'buildx-common/validation';

// Import only project schemas
import { ProjectSchema, ProjectCreateSchema } from 'buildx-common/project';

// Import only user schemas
import { UserSchema, AuthSchema } from 'buildx-common/user';
import { USER_RELATION_ALLOWED_FIELDS, sanitizeUserRelationDocument } from 'buildx-common/user';

// Import only field schemas
import { FieldSchema, BaseFieldSchema } from 'buildx-common/field';

// Import only collection schemas
import { CollectionSchema, CollectionConnectionType } from 'buildx-common/collection';

// Import only constants
import { RESERVED_NAMES, IDENTIFIER_REGEX } from 'buildx-common/constants';

// Import shared auth error codes/helpers
import { AUTH_ERROR_CODES, isTokenExpiredError, isUnauthorizedError } from "buildx-common/error";

Module Structure

The package is organized into domain-driven modules:

• /validation - Zod schemas and validation utilities
• /project - Project-related schemas and types
• /user - User and authentication schemas
  • Includes shared relation serializer helpers for safe user relation payloads (sanitizeUserRelationDocument, USER_RELATION_ALLOWED_FIELDS, isUserRelationType)
• /field - Field schemas for form definitions
• /collection - Collection and lifecycle schemas
• /constants - Shared constants and enums
• /error - Shared auth error codes and classification helpers (E02005, E02006)

See docs/MODULES.md for detailed module documentation.

Project Locale + Metadata Format

buildx-common/project defines reusable schema for project locale:

• ProjectLocaleSchema.default_language
  • Format: xx or xx-YY
  • Examples: en, th, en-US, th-TH
• ProjectLocaleSchema.timezone
  • Format: IANA timezone or UTC
  • Examples: Asia/Bangkok, America/New_York, UTC

And project-level metadata container:

• ProjectSchema.metadata: Record<string, any>
• Recommended product constants namespace: metadata.product_constants

Project logo payload compatibility:

• ProjectSchema.configuration.logo accepts both legacy single-object and array-item payload formats.
• Supported keys include name, content, path, lastModified, filename, location (plus passthrough keys).

Project partial update parsing:

• Use parseProjectUpdateInput(payload) from buildx-common/project for update flows.
• It validates with ProjectUpdateSchema and keeps only explicitly provided top-level keys.
• This prevents defaulted schema values (for omitted fields) from being injected into partial update writes.

Benefits

1. Tree-shaking: Import only what you need to reduce bundle size
2. Clear boundaries: Each module has a specific domain responsibility
3. Better organization: Related code is grouped together
4. Easier maintenance: Changes to one domain don't affect others
5. Type safety: Each module exports its own types
6. Scalability: Easy to add new modules or extend existing ones

Shared Auth Error Codes

buildx-common/error is the canonical source for cross-package auth error semantics:

• UNAUTHORIZED: E02005 (401)
• TOKEN_EXPIRED: E02006 (401)

This module is intended for datastore, SDK, and product clients to keep auth handling aligned when code/message mapping changes.

It also exports full shared ERROR_CODES (application-wide) so packages/apps can consume one source of truth instead of maintaining duplicated local error catalogs.

Publish Artifact Contract

This package publishes compiled runtime artifacts from build/ and all public subpath exports must resolve from npm installs, including:

• buildx-common/error
• buildx-common/project
• buildx-common/validation

The publish artifact contract is:

1. package.json main / module / types target build/*.
2. Published files include build/** so exports paths are physically present.
3. npm pack --dry-run must list build/error/index.{cjs,mjs,d.ts} before release.

CI/CD & Automation

• Auto PR Approve: Automatically approves eligible pull requests with no merge conflicts. See docs/AUTO_PR_APPROVE.md for details.
• Deployment PRs: Deployment PRs are auto-generated and labeled for automation.
• Auto Publish: Automated publishing and documentation deployment on merge to master.

🩺 Troubleshooting

If some module not found error, you may need to check for peer dependencies. If you encounter strange errors like:

• Metadata not working as expected with class decorators

You may need to enable the following in your tsconfig.json:

{
  "compilerOptions": {
    "emitDecoratorMetadata": true
  }
}