@oatscenter/trellis 0.100.0-rc.1

package/codec.d.ts

@@ -0,0 +1,13 @@
+import { type InferSchemaType, type SchemaLike } from "./participant.ts";
+import { Result } from "@oatscenter/result";
+import type { StaticDecode, TSchema } from "typebox";
+import { SchemaValidationError, UnexpectedError, ValidationError } from "./errors/index.ts";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function parse<T extends TSchema>(schema: T, data: JsonValue): Result<StaticDecode<T>, SchemaValidationError | ValidationError | UnexpectedError>;
+export declare function parseSchema<S extends SchemaLike>(schema: S, data: JsonValue): Result<InferSchemaType<S>, SchemaValidationError | ValidationError | UnexpectedError>;
+/** Parses unknown JSON-compatible data with an arbitrary Trellis schema. */
+export declare function parseUnknownSchema(schema: SchemaLike, data: JsonValue): Result<unknown, SchemaValidationError | ValidationError | UnexpectedError>;
+export declare function encode<T extends TSchema>(schema: T, data: unknown): Result<string, SchemaValidationError | ValidationError | UnexpectedError>;
+export declare function encodeSchema(schema: SchemaLike, data: unknown): Result<string, SchemaValidationError | ValidationError | UnexpectedError>;

package/codec.js

@@ -0,0 +1,192 @@
+import { unwrapSchema, } from "./participant.js";
+import { Result } from "@oatscenter/result";
+import { EncodeError, ParseError, Value } from "typebox/value";
+import { SchemaValidationError, UnexpectedError, ValidationError, } from "./errors/index.js";
+const X_TRELLIS_VALIDATION = "x-trellis-validation";
+function readTrellisValidationExtension(schema) {
+    if (schema === null || schema === undefined || typeof schema !== "object") {
+        return undefined;
+    }
+    const ext = schema[X_TRELLIS_VALIDATION];
+    if (ext === null || ext === undefined || typeof ext !== "object") {
+        return undefined;
+    }
+    return ext;
+}
+function resolveSchemaNode(root, schemaPath) {
+    if (!schemaPath.startsWith("#/")) {
+        if (schemaPath === "#")
+            return root;
+        return undefined;
+    }
+    const parts = schemaPath.slice(2).split("/").map(decodeURIComponent);
+    let current = root;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function resolveRequiredErrorNode(root, error) {
+    const params = error.params;
+    const missingProperty = (params?.missingProperty ??
+        params?.requiredProperties?.[0]);
+    if (!missingProperty)
+        return undefined;
+    const objNode = resolveSchemaNode(root, error.schemaPath);
+    if (!objNode || typeof objNode !== "object")
+        return undefined;
+    const properties = objNode.properties;
+    if (!properties || typeof properties !== "object")
+        return undefined;
+    return properties[missingProperty];
+}
+const ALLOWED_HINT_KEYWORDS = new Set([
+    "required",
+    "minItems",
+    "maxItems",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "pattern",
+    "format",
+    "enum",
+    "const",
+]);
+function keywordAllowsHint(keyword) {
+    return ALLOWED_HINT_KEYWORDS.has(keyword);
+}
+function typeboxIssueToPath(error) {
+    if (error.keyword === "required") {
+        const params = error.params;
+        const missingProperty = (params?.missingProperty ??
+            params?.requiredProperties?.[0]);
+        if (missingProperty) {
+            return error.instancePath
+                ? `${error.instancePath}/${missingProperty}`
+                : `/${missingProperty}`;
+        }
+    }
+    return error.instancePath || error.schemaPath;
+}
+function collectValidationIssues(root, errors) {
+    const annotated = [];
+    const unannotated = [];
+    for (const error of [...errors]) {
+        const schemaNode = error.keyword === "required"
+            ? resolveRequiredErrorNode(root, error)
+            : resolveSchemaNode(root, error.schemaPath);
+        const extension = schemaNode !== undefined
+            ? readTrellisValidationExtension(schemaNode)
+            : undefined;
+        if (extension !== undefined &&
+            keywordAllowsHint(error.keyword) &&
+            extension.issues?.[error.keyword] !== undefined) {
+            const hint = extension.issues[error.keyword];
+            if (hint.code !== undefined) {
+                annotated.push({
+                    path: typeboxIssueToPath(error),
+                    schemaPath: error.schemaPath,
+                    keyword: error.keyword,
+                    code: hint.code,
+                    message: hint.message || error.message,
+                    label: hint.label ?? extension.label,
+                    note: hint.note ?? extension.note,
+                    i18nKey: hint.i18nKey,
+                    severity: hint.severity ?? "error",
+                    params: error.params,
+                });
+                continue;
+            }
+        }
+        unannotated.push(error);
+    }
+    return { annotated, unannotated };
+}
+function buildValidationError(schema, data, errors, cause) {
+    const { annotated, unannotated } = collectValidationIssues(schema, errors);
+    if (annotated.length > 0 && unannotated.length === 0) {
+        return new SchemaValidationError({ issues: annotated, cause });
+    }
+    return new ValidationError({
+        errors: unannotated.length > 0
+            ? unannotated
+            : annotated.map((i) => ({ path: i.path, message: i.message })),
+        cause,
+    });
+}
+function parseWithSchema(schema, data) {
+    return Value.Parse(schema, data);
+}
+function encodeWithSchema(schema, data) {
+    return JSON.stringify(Value.Encode(schema, data), (_key, value) => typeof value === "bigint" ? value.toString() : value);
+}
+export function parse(schema, data) {
+    try {
+        return Result.ok(parseWithSchema(schema, data));
+    }
+    catch (cause) {
+        if (cause instanceof ParseError) {
+            const errors = Value.Errors(schema, data);
+            return Result.err(buildValidationError(schema, data, errors, cause));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}
+export function parseSchema(schema, data) {
+    const raw = unwrapSchema(schema);
+    try {
+        return Result.ok(parseWithSchema(raw, data));
+    }
+    catch (cause) {
+        if (cause instanceof ParseError) {
+            const errors = Value.Errors(raw, data);
+            return Result.err(buildValidationError(raw, data, errors, cause));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}
+/** Parses unknown JSON-compatible data with an arbitrary Trellis schema. */
+export function parseUnknownSchema(schema, data) {
+    const raw = unwrapSchema(schema);
+    try {
+        return Result.ok(parseWithSchema(raw, data));
+    }
+    catch (cause) {
+        if (cause instanceof ParseError) {
+            const errors = Value.Errors(raw, data);
+            return Result.err(buildValidationError(raw, data, errors, cause));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}
+export function encode(schema, data) {
+    try {
+        return Result.ok(encodeWithSchema(schema, data));
+    }
+    catch (cause) {
+        if (cause instanceof EncodeError) {
+            const errors = Value.Errors(schema, data);
+            return Result.err(buildValidationError(schema, data, errors, cause));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}
+export function encodeSchema(schema, data) {
+    const raw = unwrapSchema(schema);
+    try {
+        return Result.ok(encodeWithSchema(raw, data));
+    }
+    catch (cause) {
+        if (cause instanceof EncodeError) {
+            const errors = Value.Errors(raw, data);
+            return Result.err(buildValidationError(raw, data, errors, cause));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}

package/connection.d.ts

@@ -0,0 +1,107 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import { type LoggerLike } from "./globals.ts";
+/** Identifies the Trellis runtime that owns a connection. */
+export type TrellisConnectionKind = "client" | "device" | "service";
+/** Framework-neutral lifecycle phase for an observed Trellis transport. */
+export type TrellisConnectionPhase = "connected" | "disconnected" | "reconnecting" | "error" | "closed";
+/** Diagnostic metadata copied from the underlying transport without exposing raw handles. */
+export type TrellisConnectionTransportMetadata = {
+    readonly name?: string;
+    readonly event?: string;
+    readonly server?: string;
+    readonly data?: unknown;
+    readonly error?: unknown;
+};
+/** Current framework-neutral connection status. */
+export type TrellisConnectionStatus = {
+    readonly kind: TrellisConnectionKind;
+    readonly phase: TrellisConnectionPhase;
+    readonly observedAt: Date;
+    readonly transport?: TrellisConnectionTransportMetadata;
+};
+/** Receives connection status changes. */
+export type TrellisConnectionStatusListener = (status: TrellisConnectionStatus) => void;
+/** Narrow transport shape used by Trellis connection lifecycle observation. */
+export type TrellisConnectionStatusTransport = {
+    status?: () => AsyncIterable<unknown>;
+    closed: () => Promise<void | Error>;
+    close: () => Promise<void>;
+    isClosed?: () => boolean;
+    getServer?: () => string | undefined;
+};
+/** Options for constructing a manually controlled Trellis connection lifecycle. */
+export type TrellisConnectionOptions = {
+    kind: TrellisConnectionKind;
+    initialStatus?: TrellisConnectionStatus;
+    availability?: TrellisAvailability;
+    close?: () => Promise<void>;
+    stopObserving?: () => void | Promise<void>;
+    log?: LoggerLike | false;
+};
+/** Options for observing a transport-backed Trellis connection lifecycle. */
+export type ObserveTrellisConnectionOptions = {
+    kind: TrellisConnectionKind;
+    transport: TrellisConnectionStatusTransport;
+    transportName?: string;
+    log?: LoggerLike | false;
+    lifecycleLog?: TrellisConnectionLifecycleLogOptions;
+    availability?: TrellisAvailability;
+    onTransportEvent?: (event: unknown) => void;
+};
+/** Options for observing a NATS-backed Trellis connection lifecycle. */
+export type ObserveNatsTrellisConnectionOptions = {
+    kind: TrellisConnectionKind;
+    nc: NatsConnection;
+    log?: LoggerLike | false;
+    lifecycleLog?: TrellisConnectionLifecycleLogOptions;
+    availability?: TrellisAvailability;
+    onTransportEvent?: (event: unknown) => void;
+};
+/** Options for logging transport lifecycle events with Trellis runtime context. */
+export type TrellisConnectionLifecycleLogOptions = {
+    log: LoggerLike;
+    context: Record<string, unknown>;
+};
+/** Immutable installed availability for optional participant surfaces. */
+export type TrellisAvailability = Readonly<{
+    capabilities: Readonly<Record<string, boolean>>;
+    resources: Readonly<Record<string, boolean>>;
+}>;
+declare const installAvailability: unique symbol;
+/**
+ * Framework-neutral Trellis connection lifecycle handle.
+ *
+ * The class stores the latest transport-neutral status, delivers it immediately
+ * to subscribers, and owns lifecycle cleanup without exposing raw transport
+ * handles to framework adapters.
+ */
+export declare class TrellisConnection {
+    #private;
+    /** Creates a Trellis connection lifecycle handle. */
+    constructor(options: TrellisConnectionOptions);
+    /** Returns the latest observed connection status. */
+    get status(): TrellisConnectionStatus;
+    /** Returns the current immutable installed availability snapshot. */
+    availability(): TrellisAvailability;
+    /** Yields the current availability and each subsequent installed replacement. */
+    watchAvailability(): AsyncIterable<TrellisAvailability>;
+    [installAvailability](availability: TrellisAvailability): void;
+    /**
+     * Subscribes to status changes and immediately delivers the current status.
+     *
+     * The returned function removes the listener. Calling it more than once is
+     * safe.
+     */
+    subscribe(listener: TrellisConnectionStatusListener): () => void;
+    /** Stops status observation without closing the underlying transport. */
+    stopObserving(): void;
+    /** Closes the underlying transport and publishes a terminal closed status. */
+    close(): Promise<void>;
+    /** Publishes a new status to all active listeners. */
+    setStatus(status: TrellisConnectionStatus): void;
+}
+/** Observes a narrow transport status stream as a Trellis connection lifecycle. */
+export declare function observeTrellisConnection(options: ObserveTrellisConnectionOptions): TrellisConnection;
+/** Observes a NATS connection without exposing the raw NATS handle publicly. */
+export declare function observeNatsTrellisConnection(options: ObserveNatsTrellisConnectionOptions): TrellisConnection;
+export {};