lib.schema

@lssm-tech/lib.schema

Website: https://contractspec.io

Schema utilities for Zod, JSON Schema, and GraphQL.

EnumType keeps domain strings unchanged in Zod and JSON Schema. Its GraphQL projection replaces invalid identifier characters with underscores and prefixes invalid leading characters or reserved literals with VALUE_. GraphQL parsing and serialization map those wire names to the original domain strings. Name collisions are rejected explicitly; existing valid GraphQL names do not change.

What It Provides

• Layer: lib.
• Consumers: nearly all libs, bundles, and apps.
• Related ContractSpec packages include @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
• Related ContractSpec packages include @lssm-tech/tool.bun, @lssm-tech/tool.typescript.

Installation

npm install @lssm-tech/lib.schema

or

bun add @lssm-tech/lib.schema

Usage

Import the root entrypoint from @lssm-tech/lib.schema, or choose a documented subpath when you only need one part of the package surface.

Architecture

• src/entity is part of the package's public or composition surface.
• src/EnumType.test.ts is part of the package's public or composition surface.
• src/EnumType.ts is part of the package's public or composition surface.
• src/FieldType.test.ts is part of the package's public or composition surface.
• src/FieldType.ts is part of the package's public or composition surface.
• src/GraphQLSchemaType.test.ts is part of the package's public or composition surface.
• src/GraphQLSchemaType.ts is part of the package's public or composition surface.
• src/index.ts is the root public barrel and package entrypoint.

Public Entry Points

• Export . resolves through ./src/index.ts.
• Export ./entity resolves through ./src/entity/index.ts.
• Export ./entity/defineEntity resolves through ./src/entity/defineEntity.ts.
• Export ./entity/generator resolves through ./src/entity/generator.ts.
• Export ./entity/types resolves through ./src/entity/types.ts.
• Export ./EnumType resolves through ./src/EnumType.ts.
• Export ./FieldType resolves through ./src/FieldType.ts.
• Export ./GraphQLSchemaType resolves through ./src/GraphQLSchemaType.ts.
• Export ./JsonSchemaType resolves through ./src/JsonSchemaType.ts.
• Export ./ScalarFactoryCache resolves through ./src/ScalarFactoryCache.ts.
• The package publishes 14 total export subpaths; keep docs aligned with package.json.

Local Commands

Builds use explicit schema, entity, and generator roots with the existing 14 manifest subpaths retained as compatibility roots. The builder emits their local module closure once per supported target and preserves shared module identity. Source-file discovery does not add public exports; intentional public additions update both export maps before implementation. Node, Bun, browser, and declaration targets retain their existing paths.

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.

Notes

• Preserve multi-surface consistency: Zod, GraphQL, and JSON Schema representations must stay aligned.
• Prefer additive changes; avoid silently weakening validation or changing scalar semantics.
• Do not edit dist/; source of truth is src/.

Graph & Timeline Primitives

@lssm-tech/lib.schema ships defineEntity and field helpers for Layer-2 entity contract authoring alongside defineContractEntity from @lssm-tech/lib.contracts-spec:

import { defineEntity, field } from "@lssm-tech/lib.schema/entity/defineEntity";

Field helpers: field.id(), field.string(), field.email(), field.createdAt(), field.updatedAt(), field.boolean(), field.int(), field.float().

Pair these with defineContractEntity when you need typed entity schemas for entity-declarative graph data views. They are entity-contract authoring utilities, not general-purpose schema tools.

See AGENTS.md for full details.

The GraphQL Maybe type uses its existing .js import path so emitted SchemaModel declarations resolve in strict NodeNext consumers. The executable schema body and nullable semantics are unchanged; tsconfig.graphql-maybe-compat.json verifies the canonical type without skipping declaration checks.