@nats-io/services 3.0.0-2

package/lib/types.d.ts

@@ -0,0 +1,246 @@
+import type { Msg, Nanos, NatsError, PublishOptions, QueuedIterator } from "@nats-io/nats-core";
+export interface ServiceMsg extends Msg {
+    respondError(code: number, description: string, data?: Uint8Array, opts?: PublishOptions): boolean;
+}
+export type ServiceHandler = (err: NatsError | null, msg: ServiceMsg) => void;
+/**
+ * A service Endpoint
+ */
+export type Endpoint = {
+    /**
+     * Subject where the endpoint listens
+     */
+    subject: string;
+    /**
+     * An optional handler - if not set the service is an iterator
+     * @param err
+     * @param msg
+     */
+    handler?: ServiceHandler;
+    /**
+     * Optional metadata about the endpoint
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Optional queue group to run this particular endpoint in. The service's configuration
+     * queue configuration will be used. See {@link ServiceConfig}.
+     */
+    queue?: string;
+};
+export type EndpointOptions = Partial<Endpoint>;
+export type EndpointInfo = {
+    name: string;
+    subject: string;
+    metadata?: Record<string, string>;
+    queue_group?: string;
+};
+export interface ServiceGroup {
+    /**
+     * The name of the endpoint must be a simple subject token with no wildcards
+     * @param name
+     * @param opts is either a handler or a more complex options which allows a
+     *  subject, handler, and/or schema
+     */
+    addEndpoint(name: string, opts?: ServiceHandler | EndpointOptions): QueuedIterator<ServiceMsg>;
+    /**
+     * A group is a subject prefix from which endpoints can be added.
+     * Can be empty to allow for prefixes or tokens that are set at runtime
+     * without requiring editing of the service.
+     * Note that an optional queue can be specified, all endpoints added to
+     * the group, will use the specified queue unless the endpoint overrides it.
+     * see {@link EndpointOptions} and {@link ServiceConfig}.
+     * @param subject
+     * @param queue
+     */
+    addGroup(subject?: string, queue?: string): ServiceGroup;
+}
+export type ServiceMetadata = {
+    metadata?: Record<string, string>;
+};
+export declare enum ServiceResponseType {
+    STATS = "io.nats.micro.v1.stats_response",
+    INFO = "io.nats.micro.v1.info_response",
+    PING = "io.nats.micro.v1.ping_response"
+}
+export interface ServiceResponse {
+    /**
+     * Response type schema
+     */
+    type: ServiceResponseType;
+}
+export type ServiceIdentity = ServiceResponse & ServiceMetadata & {
+    /**
+     * The kind of the service reporting the stats
+     */
+    name: string;
+    /**
+     * The unique ID of the service reporting the stats
+     */
+    id: string;
+    /**
+     * A version for the service
+     */
+    version: string;
+};
+export type NamedEndpointStats = {
+    /**
+     * The name of the endpoint
+     */
+    name: string;
+    /**
+     * The subject the endpoint is listening on
+     */
+    subject: string;
+    /**
+     * The number of requests received by the endpoint
+     */
+    num_requests: number;
+    /**
+     * Number of errors that the endpoint has raised
+     */
+    num_errors: number;
+    /**
+     * If set, the last error triggered by the endpoint
+     */
+    last_error?: string;
+    /**
+     * A field that can be customized with any data as returned by stats handler see {@link ServiceConfig}
+     */
+    data?: unknown;
+    /**
+     * Total processing_time for the service
+     */
+    processing_time: Nanos;
+    /**
+     * Average processing_time is the total processing_time divided by the num_requests
+     */
+    average_processing_time: Nanos;
+    /**
+     * The queue group the endpoint is listening on
+     */
+    queue_group?: string;
+};
+/**
+ * Statistics for an endpoint
+ */
+export type EndpointStats = ServiceIdentity & {
+    endpoints?: NamedEndpointStats[];
+    /**
+     * ISO Date string when the service started
+     */
+    started: string;
+};
+export type ServiceInfo = ServiceIdentity & {
+    /**
+     * Description for the service
+     */
+    description: string;
+    /**
+     * Service metadata
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Information about the Endpoints
+     */
+    endpoints: EndpointInfo[];
+};
+export type ServiceConfig = {
+    /**
+     * A type for a service
+     */
+    name: string;
+    /**
+     * A version identifier for the service
+     */
+    version: string;
+    /**
+     * Description for the service
+     */
+    description?: string;
+    /**
+     * A customized handler for the stats of an endpoint. The
+     * data returned by the endpoint will be serialized as is
+     * @param endpoint
+     */
+    statsHandler?: (endpoint: Endpoint) => Promise<unknown | null>;
+    /**
+     * Optional metadata about the service
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Optional queue group to run the service in. By default,
+     * then queue name is "q". Note that this configuration will
+     * be the default for all endpoints and groups.
+     */
+    queue?: string;
+};
+/**
+ * The stats of a service
+ */
+export type ServiceStats = ServiceIdentity & EndpointStats;
+export interface Service extends ServiceGroup {
+    /**
+     * A promise that gets resolved to null or Error once the service ends.
+     * If an error, then service exited because of an error.
+     */
+    stopped: Promise<null | Error>;
+    /**
+     * True if the service is stopped
+     */
+    isStopped: boolean;
+    /**
+     * Returns the stats for the service.
+     */
+    stats(): Promise<ServiceStats>;
+    /**
+     * Returns a service info for the service
+     */
+    info(): ServiceInfo;
+    /**
+     * Returns the identity used by this service
+     */
+    ping(): ServiceIdentity;
+    /**
+     * Resets all the stats
+     */
+    reset(): void;
+    /**
+     * Stop the service returning a promise once the service completes.
+     * If the service was stopped due to an error, that promise resolves to
+     * the specified error
+     */
+    stop(err?: Error): Promise<null | Error>;
+}
+export declare const ServiceErrorHeader = "Nats-Service-Error";
+export declare const ServiceErrorCodeHeader = "Nats-Service-Error-Code";
+export declare class ServiceError extends Error {
+    code: number;
+    constructor(code: number, message: string);
+    static isServiceError(msg: Msg): boolean;
+    static toServiceError(msg: Msg): ServiceError | null;
+}
+export declare enum ServiceVerb {
+    PING = "PING",
+    STATS = "STATS",
+    INFO = "INFO"
+}
+export interface ServiceClient {
+    /**
+     * Pings services
+     * @param name - optional
+     * @param id - optional
+     */
+    ping(name?: string, id?: string): Promise<QueuedIterator<ServiceIdentity>>;
+    /**
+     * Requests all the stats from services
+     * @param name
+     * @param id
+     */
+    stats(name?: string, id?: string): Promise<QueuedIterator<ServiceStats>>;
+    /**
+     * Requests info from services
+     * @param name
+     * @param id
+     */
+    info(name?: string, id?: string): Promise<QueuedIterator<ServiceInfo>>;
+}

package/lib/types.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceVerb = exports.ServiceError = exports.ServiceErrorCodeHeader = exports.ServiceErrorHeader = exports.ServiceResponseType = void 0;
+var ServiceResponseType;
+(function (ServiceResponseType) {
+    ServiceResponseType["STATS"] = "io.nats.micro.v1.stats_response";
+    ServiceResponseType["INFO"] = "io.nats.micro.v1.info_response";
+    ServiceResponseType["PING"] = "io.nats.micro.v1.ping_response";
+})(ServiceResponseType || (exports.ServiceResponseType = ServiceResponseType = {}));
+exports.ServiceErrorHeader = "Nats-Service-Error";
+exports.ServiceErrorCodeHeader = "Nats-Service-Error-Code";
+class ServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+    static isServiceError(msg) {
+        return ServiceError.toServiceError(msg) !== null;
+    }
+    static toServiceError(msg) {
+        const scode = msg?.headers?.get(exports.ServiceErrorCodeHeader) || "";
+        if (scode !== "") {
+            const code = parseInt(scode) || 400;
+            const description = msg?.headers?.get(exports.ServiceErrorHeader) || "";
+            return new ServiceError(code, description.length ? description : scode);
+        }
+        return null;
+    }
+}
+exports.ServiceError = ServiceError;
+var ServiceVerb;
+(function (ServiceVerb) {
+    ServiceVerb["PING"] = "PING";
+    ServiceVerb["STATS"] = "STATS";
+    ServiceVerb["INFO"] = "INFO";
+})(ServiceVerb || (exports.ServiceVerb = ServiceVerb = {}));
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../build/src/types.ts"],"names":[],"mappings":";;;AA+EA,IAAY,mBAIX;AAJD,WAAY,mBAAmB;IAC7B,gEAAyC,CAAA;IACzC,8DAAuC,CAAA;IACvC,8DAAuC,CAAA;AACzC,CAAC,EAJW,mBAAmB,mCAAnB,mBAAmB,QAI9B;AAmKY,QAAA,kBAAkB,GAAG,oBAAoB,CAAC;AAC1C,QAAA,sBAAsB,GAAG,yBAAyB,CAAC;AAEhE,MAAa,YAAa,SAAQ,KAAK;IACrC,IAAI,CAAS;IAEb,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,GAAQ;QAC5B,OAAO,YAAY,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IACnD,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,GAAQ;QAC5B,MAAM,KAAK,GAAG,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,8BAAsB,CAAC,IAAI,EAAE,CAAC;QAC9D,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;YACpC,MAAM,WAAW,GAAG,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,0BAAkB,CAAC,IAAI,EAAE,CAAC;YAChE,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AArBD,oCAqBC;AAED,IAAY,WAIX;AAJD,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,8BAAe,CAAA;IACf,4BAAa,CAAA;AACf,CAAC,EAJW,WAAW,2BAAX,WAAW,QAItB"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nats-io/services",
+  "version": "3.0.0-2",
+  "files": [
+    "lib/",
+    "build/src/"
+  ],
+  "types": "./lib/mod.d.js",
+  "exports": {
+    ".": "./lib/mod.js",
+    "./internal": "./lib/internal_mod.js"
+  },
+  "license": "Apache-2.0",
+  "private": false,
+  "scripts": {
+    "real-clean": "npm run clean && shx rm -Rf ./node_modules",
+    "clean": "shx rm -Rf ./build ./lib ./docs",
+    "pre-process": "npm run clean && deno run -A ../bin/cjs-fix-imports.ts -o ./build/src ./src",
+    "build-cjs": "npm run pre-process && tsc",
+    "build": "npm run build-cjs",
+    "doc": "npm run build && node_modules/.bin/typedoc --out ../docs/services && touch ../docs/services/.nojekyll",
+    "prepack": "npm run build"
+  },
+  "keywords": [],
+  "author": {
+    "name": "The NATS Authors"
+  },
+  "description": "services library - this library implements all the base functionality for NATS services for javascript clients",
+  "dependencies": {
+    "@nats-io/nats-core": "~3.0.0-19"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "shx": "^0.3.4",
+    "typedoc": "^0.26.5",
+    "typescript": "^5.5.4"
+  }
+}