@unispechq/unispec-js-core

Base layer for UniSpec adapters in JavaScript/TypeScript.

This package is framework-agnostic. It provides shared types and UniSpec document builders, plus convenient wrappers around @unispechq/unispec-core for REST, GraphQL, and WebSocket.

Idea: you write an adapter for any JS/TS framework (Express, NestJS, Fastify, Koa, etc.), convert the data to the types from @unispechq/unispec-js-core, and then the core assembles and validates the UniSpec document.

Features

• Shared types for describing services and REST routes:
  • FrameworkServiceMetadata
  • FrameworkRouteMetadata
• Protocol-level types for UniSpec:
  • REST: UniSpecRestPaths, UniSpecRestDocument
  • GraphQL: UniSpecGraphQLProtocol, UniSpecGraphQLOperations, UniSpecGraphQLSchema
  • WebSocket: UniSpecWebSocketProtocol, UniSpecWebSocketChannel, UniSpecWebSocketMessage
• UniSpec document builders:
  • REST only: buildUniSpecDocumentFromRest
  • GraphQL only: buildUniSpecDocumentFromGraphQL
  • WebSocket only: buildUniSpecDocumentFromWebSocket
  • REST + GraphQL: buildUniSpecDocumentFromRestAndGraphQL
  • REST + WebSocket: buildUniSpecDocumentFromRestAndWebSocket
• Wrappers around validateUniSpec / normalizeUniSpec from @unispechq/unispec-core:
  • REST: validateRestUniSpecDocument, normalizeRestUniSpecDocument
  • GraphQL: validateGraphQLUniSpecDocument, normalizeGraphQLUniSpecDocument
  • WebSocket: validateWebSocketUniSpecDocument, normalizeWebSocketUniSpecDocument
  • REST + GraphQL: validateRestAndGraphQLUniSpecDocument, normalizeRestAndGraphQLUniSpecDocument
  • REST + WebSocket: validateRestAndWebSocketUniSpecDocument, normalizeRestAndWebSocketUniSpecDocument

When to use this package

Use @unispechq/unispec-js-core when you:

• are building a UniSpec adapter for your JS/TS framework;
• do not want to manually construct the UniSpecDocument structure and dive into unispec-core internals;
• want a unified type contract and UniSpec building flow shared across different adapters.

Example: simple REST adapter

Assume you have a framework MyFramework that lets you access the list of routes.

import {
  type FrameworkServiceMetadata,
  type FrameworkRouteMetadata,
  buildUniSpecDocumentFromRest,
  validateRestUniSpecDocument,
  normalizeRestUniSpecDocument
} from "@unispechq/unispec-js-core";

async function buildUniSpecForMyFrameworkApp(app: MyFrameworkApp) {
  const service: FrameworkServiceMetadata = {
    id: "my-service",
    name: "My Service",
    version: "1.0.0"
  };

  const routes: FrameworkRouteMetadata[] = app.getRoutes().map((r) => ({
    method: r.method,
    path: r.path
    // optionally you can fill in summary/description/params/response, etc.
  }));

  // Build the UniSpec document
  const document = buildUniSpecDocumentFromRest({ service, routes });

  // Validate against the official UniSpec schemas
  const validation = await validateRestUniSpecDocument({ service, routes });
  if (!validation.valid) {
    console.error("UniSpec validation failed", validation.errors);
  }

  // Normalized document (stable field order, etc.)
  const normalized = normalizeRestUniSpecDocument({ service, routes });

  return normalized;
}

Example: REST + GraphQL

If your framework allows you to obtain a GraphQL schema (SDL and a list of operations), you can use combined build options:

import {
  type FrameworkServiceMetadata,
  type FrameworkRouteMetadata,
  type UniSpecGraphQLProtocol,
  validateRestAndGraphQLUniSpecDocument,
  normalizeRestAndGraphQLUniSpecDocument
} from "@unispechq/unispec-js-core";

async function buildUniSpecForRestAndGraphQL(
  service: FrameworkServiceMetadata,
  routes: FrameworkRouteMetadata[],
  graphql: UniSpecGraphQLProtocol
) {
  const validation = await validateRestAndGraphQLUniSpecDocument({
    service,
    routes,
    graphql
  });

  if (!validation.valid) {
    console.error("UniSpec validation failed", validation.errors);
  }

  const normalized = normalizeRestAndGraphQLUniSpecDocument({
    service,
    routes,
    graphql
  });

  return normalized;
}

The same approach works for REST + WebSocket via UniSpecWebSocketProtocol and the functions validateRestAndWebSocketUniSpecDocument / normalizeRestAndWebSocketUniSpecDocument.

Relation to other packages

• @unispechq/unispec-js-core does not define the UniSpec format and does not implement the engine — these are provided by:
  • unispec-spec — format and JSON Schemas;
  • unispec-core — validation/normalization engine.
• Express and NestJS adapters (@unispechq/unispec-express, @unispechq/unispec-nestjs) use this package as a shared layer of types and builders.
• If you are creating your own adapter, the recommended way is to build on top of @unispechq/unispec-js-core.