@uns-kit/core

Core utilities and runtime building blocks for building Unified Namespace (UNS) realtime transformers. The package bundles the process lifecycle manager, MQTT integrations, gRPC gateway helpers, configuration tooling, and shared type definitions that power the UNS ecosystem.

Note: Apps built with uns-kit are intended to be managed by the UNS Datahub controller.

uns-kit in context

uns-kit is a batteries-included toolkit for Unified Namespace applications. It standardizes MQTT wiring, auth, config schemas, and scaffolding so teams can focus on domain logic instead of boilerplate. This package is the foundation; the full toolkit includes:

| Package | Description | | --- | --- | | @uns-kit/core | Base runtime utilities (UnsProxyProcess, MQTT helpers, configuration tooling, gRPC gateway support). | | @uns-kit/api | Express plugin that exposes HTTP endpoints, handles JWT/JWKS auth, and republishes API metadata to UNS. | | @uns-kit/cron | Cron-driven scheduler that emits UNS events on a fixed cadence. | | @uns-kit/temporal | Temporal.io integration that wires workflows into UnsProxyProcess. | | @uns-kit/cli | Command line tool for scaffolding new UNS applications. |

Installation

pnpm add @uns-kit/core
# or
npm install @uns-kit/core

Key Features

• UnsProxyProcess – plugin-ready runtime for managing UNS proxy instances and MQTT wiring.
• MQTT helpers – resilient publishers, topic builders, throttled queues, and handover support.
• Configuration utilities – Zod-powered config schema generation and secret resolution helpers.
• gRPC gateway helpers – infrastructure to bridge Python workers into the UNS message fabric.
• GraphQL tooling – utilities such as refresh-uns that rebuild UNS topic/tag unions from your environment.

Usage

Most projects start by creating an UnsProxyProcess and registering plugins:

import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";

const process = new UnsProxyProcess("mqtt-broker.svc:1883", { processName: "my-rtt" });

See the individual plugin packages (@uns-kit/cron, @uns-kit/api, @uns-kit/temporal) for examples on extending the process with runtime capabilities. For a list of topics published by core (and the API plugin), see ../../docs/uns-topics.md.

Refresh UNS topic/tag/attribute unions

The package ships a CLI tool that regenerates strongly-typed UNS topics and tags based on the live GraphQL schema:

pnpm run refresh-uns

When configured via uns-kit configure-codegen, this script lives in your project package.json and writes into src/uns/ (topics, tags, and attribute summaries for IntelliSense).

Generate UNS dictionary (object types & attributes with descriptions)

Use packages/uns-core/src/tools/generate-uns-dictionary.ts to turn a JSON dictionary into a TypeScript helper. No network or GraphQL calls are involved.

pnpm tsx packages/uns-core/src/tools/generate-uns-dictionary.ts \ 
  --input uns-dictionary.json \            # base JSON
  --output src/uns/uns-dictionary.generated.ts \ 
  --lang sl                                # pick language code from descriptions

• Reads the provided JSON and emits TypeScript constants, description maps, and helper getters for IntelliSense and metadata emission.

To generate both dictionary and measurements in one step, use the wrapper:

pnpm tsx packages/uns-core/src/tools/generate-uns-reference.ts \
  --dictionary uns-dictionary.json \
  --dictionary-output src/uns/uns-dictionary.generated.ts \
  --measurements uns-measurements.json \
  --measurements-output src/uns/uns-measurements.generated.ts \
  --lang sl

Infisical secret resolution in development

• The resolver looks for SecretResolverOptions.infisical.fetchSecret, then INFISICAL_TOKEN/INFISICAL_PERSONAL_TOKEN, then /run/secrets/infisical_token (or /var/lib/uns/secrets/infisical_token).
• If no fetcher/token is available, the resolver now logs a warning and returns the placeholder default, or undefined when optional: true; required secrets still trigger onMissingSecret before throwing.
• If Infisical is configured but the host is unreachable (e.g., DNS/network failure), the resolver warns and falls back to the same default/optional handling, reusing a cached value when present; required secrets throw with the original error message.
• To inspect what would be used, call resolveInfisicalConfig() to get { token, projectId, siteUrl } via the same lookup rules.
• Use this to run locally without Infisical: mark dev-only secrets as optional or give default values, and provide real tokens only in production.

Development

# Lint and type-check the sources
pnpm run typecheck

# Emit JavaScript and declaration files to dist/
pnpm run build

License

MIT © Aljoša Vister