@start9labs/start-sdk 0.4.0-beta.50 → 0.4.0-beta.52

package/base/lib/util/deepMerge.js.map

@@ -1 +1 @@
-{"version":3,"file":"deepMerge.js","sourceRoot":"","sources":["../../../../base/lib/util/deepMerge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deepMerge.js","sourceRoot":"","sources":["../../../../base/lib/util/deepMerge.ts"],"names":[],"mappings":"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"}

package/base/lib/util/getDefaultString.d.ts

@@ -1,2 +1,10 @@
 import { DefaultString } from '../actions/input/inputSpecTypes';
+/**
+ * Resolves a DefaultString spec into a concrete string value.
+ * If the spec is a plain string, returns it directly.
+ * If it is a random-string specification, generates a random string accordingly.
+ *
+ * @param defaultSpec - A string literal or a random-string generation spec
+ * @returns The resolved default string value
+ */
 export declare function getDefaultString(defaultSpec: DefaultString): string;

package/base/lib/util/getDefaultString.js

@@ -2,6 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDefaultString = getDefaultString;
 const getRandomString_1 = require("./getRandomString");
+/**
+ * Resolves a DefaultString spec into a concrete string value.
+ * If the spec is a plain string, returns it directly.
+ * If it is a random-string specification, generates a random string accordingly.
+ *
+ * @param defaultSpec - A string literal or a random-string generation spec
+ * @returns The resolved default string value
+ */
 function getDefaultString(defaultSpec) {
     if (typeof defaultSpec === 'string') {
         return defaultSpec;

package/base/lib/util/getDefaultString.js.map

@@ -1 +1 @@
-{"version":3,"file":"getDefaultString.js","sourceRoot":"","sources":["../../../../base/lib/util/getDefaultString.ts"],"names":[],"mappings":";;AAGA,4CAMC;AARD,uDAAmD;AAEnD,SAAgB,gBAAgB,CAAC,WAA0B;IACzD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,WAAW,CAAA;IACpB,CAAC;SAAM,CAAC;QACN,OAAO,IAAA,iCAAe,EAAC,WAAW,CAAC,CAAA;IACrC,CAAC;AACH,CAAC"}
+{"version":3,"file":"getDefaultString.js","sourceRoot":"","sources":["../../../../base/lib/util/getDefaultString.ts"],"names":[],"mappings":";;AAWA,4CAMC;AAhBD,uDAAmD;AAEnD;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAAC,WAA0B;IACzD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,WAAW,CAAA;IACpB,CAAC;SAAM,CAAC;QACN,OAAO,IAAA,iCAAe,EAAC,WAAW,CAAC,CAAA;IACrC,CAAC;AACH,CAAC"}

package/base/lib/util/graph.d.ts

@@ -1,20 +1,77 @@
+/**
+ * A vertex (node) in a directed graph, holding metadata and a list of connected edges.
+ * @typeParam VMetadata - The type of metadata stored on vertices
+ * @typeParam EMetadata - The type of metadata stored on edges
+ */
 export type Vertex<VMetadata = null, EMetadata = null> = {
     metadata: VMetadata;
     edges: Array<Edge<EMetadata, VMetadata>>;
 };
+/**
+ * A directed edge connecting two vertices, with its own metadata.
+ * @typeParam EMetadata - The type of metadata stored on edges
+ * @typeParam VMetadata - The type of metadata stored on the connected vertices
+ */
 export type Edge<EMetadata = null, VMetadata = null> = {
     metadata: EMetadata;
     from: Vertex<VMetadata, EMetadata>;
     to: Vertex<VMetadata, EMetadata>;
 };
+/**
+ * A directed graph data structure supporting vertex/edge management and graph traversal algorithms
+ * including breadth-first search, reverse BFS, and shortest path computation.
+ *
+ * @typeParam VMetadata - The type of metadata stored on vertices
+ * @typeParam EMetadata - The type of metadata stored on edges
+ */
 export declare class Graph<VMetadata = null, EMetadata = null> {
     private readonly vertices;
     constructor();
+    /**
+     * Serializes the graph to a JSON string for debugging.
+     * @param metadataRepr - Optional function to transform metadata values before serialization
+     * @returns A pretty-printed JSON string of the graph structure
+     */
     dump(metadataRepr?: (metadata: VMetadata | EMetadata) => any): string;
+    /**
+     * Adds a new vertex to the graph, optionally connecting it to existing vertices via edges.
+     * @param metadata - The metadata to attach to the new vertex
+     * @param fromEdges - Edges pointing from existing vertices to this new vertex
+     * @param toEdges - Edges pointing from this new vertex to existing vertices
+     * @returns The newly created vertex
+     */
     addVertex(metadata: VMetadata, fromEdges: Array<Omit<Edge<EMetadata, VMetadata>, 'to'>>, toEdges: Array<Omit<Edge<EMetadata, VMetadata>, 'from'>>): Vertex<VMetadata, EMetadata>;
+    /**
+     * Returns a generator that yields all vertices matching the predicate.
+     * @param predicate - A function to test each vertex
+     * @returns A generator of matching vertices
+     */
     findVertex(predicate: (vertex: Vertex<VMetadata, EMetadata>) => boolean): Generator<Vertex<VMetadata, EMetadata>, null>;
+    /**
+     * Adds a directed edge between two existing vertices.
+     * @param metadata - The metadata to attach to the edge
+     * @param from - The source vertex
+     * @param to - The destination vertex
+     * @returns The newly created edge
+     */
     addEdge(metadata: EMetadata, from: Vertex<VMetadata, EMetadata>, to: Vertex<VMetadata, EMetadata>): Edge<EMetadata, VMetadata>;
+    /**
+     * Performs a breadth-first traversal following outgoing edges from the starting vertex or vertices.
+     * @param from - A starting vertex, or a predicate to select multiple starting vertices
+     * @returns A generator yielding vertices in BFS order
+     */
     breadthFirstSearch(from: Vertex<VMetadata, EMetadata> | ((vertex: Vertex<VMetadata, EMetadata>) => boolean)): Generator<Vertex<VMetadata, EMetadata>, null>;
+    /**
+     * Performs a reverse breadth-first traversal following incoming edges from the starting vertex or vertices.
+     * @param to - A starting vertex, or a predicate to select multiple starting vertices
+     * @returns A generator yielding vertices in reverse BFS order
+     */
     reverseBreadthFirstSearch(to: Vertex<VMetadata, EMetadata> | ((vertex: Vertex<VMetadata, EMetadata>) => boolean)): Generator<Vertex<VMetadata, EMetadata>, null>;
+    /**
+     * Finds the shortest path (by edge count) between two vertices using BFS.
+     * @param from - The starting vertex, or a predicate to select starting vertices
+     * @param to - The target vertex, or a predicate to identify target vertices
+     * @returns An array of edges forming the shortest path, or `null` if no path exists
+     */
     shortestPath(from: Vertex<VMetadata, EMetadata> | ((vertex: Vertex<VMetadata, EMetadata>) => boolean), to: Vertex<VMetadata, EMetadata> | ((vertex: Vertex<VMetadata, EMetadata>) => boolean)): Array<Edge<EMetadata, VMetadata>> | null;
 }

package/base/lib/util/graph.js

@@ -1,10 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Graph = void 0;
+/**
+ * A directed graph data structure supporting vertex/edge management and graph traversal algorithms
+ * including breadth-first search, reverse BFS, and shortest path computation.
+ *
+ * @typeParam VMetadata - The type of metadata stored on vertices
+ * @typeParam EMetadata - The type of metadata stored on edges
+ */
 class Graph {
     constructor() {
         this.vertices = [];
     }
+    /**
+     * Serializes the graph to a JSON string for debugging.
+     * @param metadataRepr - Optional function to transform metadata values before serialization
+     * @returns A pretty-printed JSON string of the graph structure
+     */
     dump(metadataRepr = (a) => a) {
         const seen = new WeakSet();
         return JSON.stringify(this.vertices, (k, v) => {
@@ -17,6 +29,13 @@ class Graph {
             return v;
         }, 2);
     }
+    /**
+     * Adds a new vertex to the graph, optionally connecting it to existing vertices via edges.
+     * @param metadata - The metadata to attach to the new vertex
+     * @param fromEdges - Edges pointing from existing vertices to this new vertex
+     * @param toEdges - Edges pointing from this new vertex to existing vertices
+     * @returns The newly created vertex
+     */
     addVertex(metadata, fromEdges, toEdges) {
         const vertex = {
             metadata,
@@ -43,6 +62,11 @@ class Graph {
         this.vertices.push(vertex);
         return vertex;
     }
+    /**
+     * Returns a generator that yields all vertices matching the predicate.
+     * @param predicate - A function to test each vertex
+     * @returns A generator of matching vertices
+     */
     findVertex(predicate) {
         const veritces = this.vertices;
         function* gen() {
@@ -55,6 +79,13 @@ class Graph {
         }
         return gen();
     }
+    /**
+     * Adds a directed edge between two existing vertices.
+     * @param metadata - The metadata to attach to the edge
+     * @param from - The source vertex
+     * @param to - The destination vertex
+     * @returns The newly created edge
+     */
     addEdge(metadata, from, to) {
         const edge = {
             metadata,
@@ -65,6 +96,11 @@ class Graph {
         edge.to.edges.push(edge);
         return edge;
     }
+    /**
+     * Performs a breadth-first traversal following outgoing edges from the starting vertex or vertices.
+     * @param from - A starting vertex, or a predicate to select multiple starting vertices
+     * @returns A generator yielding vertices in BFS order
+     */
     breadthFirstSearch(from) {
         const visited = [];
         function* rec(vertex) {
@@ -110,6 +146,11 @@ class Graph {
             return rec(from);
         }
     }
+    /**
+     * Performs a reverse breadth-first traversal following incoming edges from the starting vertex or vertices.
+     * @param to - A starting vertex, or a predicate to select multiple starting vertices
+     * @returns A generator yielding vertices in reverse BFS order
+     */
     reverseBreadthFirstSearch(to) {
         const visited = [];
         function* rec(vertex) {
@@ -155,6 +196,12 @@ class Graph {
             return rec(to);
         }
     }
+    /**
+     * Finds the shortest path (by edge count) between two vertices using BFS.
+     * @param from - The starting vertex, or a predicate to select starting vertices
+     * @param to - The target vertex, or a predicate to identify target vertices
+     * @returns An array of edges forming the shortest path, or `null` if no path exists
+     */
     shortestPath(from, to) {
         const isDone = to instanceof Function
             ? to

package/base/lib/util/graph.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../../../base/lib/util/graph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../../../base/lib/util/graph.ts"],"names":[],"mappings":"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"}

package/base/lib/util/inMs.d.ts

@@ -1 +1,16 @@
+/**
+ * Converts a human-readable time string to milliseconds.
+ * Supports units: `ms`, `s`, `m`, `h`, `d`. If a number is passed, it is returned as-is.
+ *
+ * @param time - A time string (e.g. `"500ms"`, `"1.5s"`, `"2h"`) or a numeric millisecond value
+ * @returns The time in milliseconds, or `undefined` if `time` is falsy
+ * @throws Error if the string format is invalid
+ *
+ * @example
+ * ```ts
+ * inMs("2s")   // 2000
+ * inMs("1.5h") // 5400000
+ * inMs(500)    // 500
+ * ```
+ */
 export declare const inMs: (time?: string | number) => number | undefined;

package/base/lib/util/inMs.js

@@ -24,6 +24,21 @@ const digitsMs = (digits, multiplier) => {
     const divideBy = multiplier / Math.pow(10, digits.length - 1);
     return Math.round(value * divideBy);
 };
+/**
+ * Converts a human-readable time string to milliseconds.
+ * Supports units: `ms`, `s`, `m`, `h`, `d`. If a number is passed, it is returned as-is.
+ *
+ * @param time - A time string (e.g. `"500ms"`, `"1.5s"`, `"2h"`) or a numeric millisecond value
+ * @returns The time in milliseconds, or `undefined` if `time` is falsy
+ * @throws Error if the string format is invalid
+ *
+ * @example
+ * ```ts
+ * inMs("2s")   // 2000
+ * inMs("1.5h") // 5400000
+ * inMs(500)    // 500
+ * ```
+ */
 const inMs = (time) => {
     if (typeof time === 'number')
         return time;

package/base/lib/util/inMs.js.map

@@ -1 +1 @@
-{"version":3,"file":"inMs.js","sourceRoot":"","sources":["../../../../base/lib/util/inMs.ts"],"names":[],"mappings":";;;AAAA,MAAM,cAAc,GAAG,mCAAmC,CAAA;AAE1D,MAAM,cAAc,GAAG,CAAC,IAAa,EAAE,EAAE;IACvC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAA;IACnB,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,CAAC,CAAA;IAC3B,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IAC7B,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,GAAG,EAAE,CAAA;IAClC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,GAAG,EAAE,GAAG,EAAE,CAAA;IACvC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;IAC5C,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAA;AAC1C,CAAC,CAAA;AACD,MAAM,QAAQ,GAAG,CAAC,MAAqB,EAAE,UAAkB,EAAE,EAAE;IAC7D,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,CAAA;IACrB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACvC,MAAM,QAAQ,GAAG,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAA;AACrC,CAAC,CAAA;AACM,MAAM,IAAI,GAAG,CAAC,IAAsB,EAAE,EAAE;IAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAA;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAA;IAC1C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAA;IAC7D,MAAM,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,OAAO,CAAA;IAC/C,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACvC,MAAM,UAAU,GAAG,QAAQ,CAAC,YAAY,IAAI,GAAG,CAAC,GAAG,UAAU,CAAA;IAC7D,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAEhD,OAAO,UAAU,GAAG,WAAW,CAAA;AACjC,CAAC,CAAA;AAXY,QAAA,IAAI,QAWhB"}
+{"version":3,"file":"inMs.js","sourceRoot":"","sources":["../../../../base/lib/util/inMs.ts"],"names":[],"mappings":";;;AAAA,MAAM,cAAc,GAAG,mCAAmC,CAAA;AAE1D,MAAM,cAAc,GAAG,CAAC,IAAa,EAAE,EAAE;IACvC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAA;IACnB,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,CAAC,CAAA;IAC3B,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IAC7B,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,GAAG,EAAE,CAAA;IAClC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,GAAG,EAAE,GAAG,EAAE,CAAA;IACvC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;IAC5C,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAA;AAC1C,CAAC,CAAA;AACD,MAAM,QAAQ,GAAG,CAAC,MAAqB,EAAE,UAAkB,EAAE,EAAE;IAC7D,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,CAAA;IACrB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACvC,MAAM,QAAQ,GAAG,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAA;AACrC,CAAC,CAAA;AACD;;;;;;;;;;;;;;GAcG;AACI,MAAM,IAAI,GAAG,CAAC,IAAsB,EAAE,EAAE;IAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAA;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAA;IAC1C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAA;IAC7D,MAAM,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,OAAO,CAAA;IAC/C,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACvC,MAAM,UAAU,GAAG,QAAQ,CAAC,YAAY,IAAI,GAAG,CAAC,GAAG,UAAU,CAAA;IAC7D,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAEhD,OAAO,UAAU,GAAG,WAAW,CAAA;AACjC,CAAC,CAAA;AAXY,QAAA,IAAI,QAWhB"}

package/base/lib/util/index.d.ts

@@ -7,6 +7,7 @@ export { once } from './once';
 export { asError } from './asError';
 export * as Patterns from './patterns';
 export * from './typeHelpers';
+export { GetOutboundGateway } from './GetOutboundGateway';
 export { GetSystemSmtp } from './GetSystemSmtp';
 export { Graph, Vertex } from './graph';
 export { inMs } from './inMs';

package/base/lib/util/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stringFromStdErrOut = exports.regexes = exports.deepEqual = exports.partialDiff = exports.deepMerge = exports.nullIfEmpty = exports.splitCommand = exports.inMs = exports.Graph = exports.GetSystemSmtp = exports.Patterns = exports.asError = exports.once = exports.getServiceInterfaces = exports.filledAddress = exports.getServiceInterface = exports.GetServiceInterface = exports.getDefaultString = exports.addressHostToUrl = void 0;
+exports.stringFromStdErrOut = exports.regexes = exports.deepEqual = exports.partialDiff = exports.deepMerge = exports.nullIfEmpty = exports.splitCommand = exports.inMs = exports.Graph = exports.GetSystemSmtp = exports.GetOutboundGateway = exports.Patterns = exports.asError = exports.once = exports.getServiceInterfaces = exports.filledAddress = exports.getServiceInterface = exports.GetServiceInterface = exports.getDefaultString = exports.addressHostToUrl = void 0;
 /// Currently being used
 var getServiceInterface_1 = require("./getServiceInterface");
 Object.defineProperty(exports, "addressHostToUrl", { enumerable: true, get: function () { return getServiceInterface_1.addressHostToUrl; } });
@@ -56,6 +56,8 @@ var asError_1 = require("./asError");
 Object.defineProperty(exports, "asError", { enumerable: true, get: function () { return asError_1.asError; } });
 exports.Patterns = __importStar(require("./patterns"));
 __exportStar(require("./typeHelpers"), exports);
+var GetOutboundGateway_1 = require("./GetOutboundGateway");
+Object.defineProperty(exports, "GetOutboundGateway", { enumerable: true, get: function () { return GetOutboundGateway_1.GetOutboundGateway; } });
 var GetSystemSmtp_1 = require("./GetSystemSmtp");
 Object.defineProperty(exports, "GetSystemSmtp", { enumerable: true, get: function () { return GetSystemSmtp_1.GetSystemSmtp; } });
 var graph_1 = require("./graph");

package/base/lib/util/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../base/lib/util/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wBAAwB;AACxB,6DAAwD;AAA/C,uHAAA,gBAAgB,OAAA;AACzB,uDAAqD;AAA5C,oHAAA,gBAAgB,OAAA;AACzB,uCAAoB;AAEpB,sDAAsD;AACtD,6DAI8B;AAH5B,0HAAA,mBAAmB,OAAA;AACnB,0HAAA,mBAAmB,OAAA;AACnB,oHAAA,aAAa,OAAA;AAEf,+DAA6D;AAApD,4HAAA,oBAAoB,OAAA;AAC7B,+BAA6B;AAApB,4FAAA,IAAI,OAAA;AACb,qCAAmC;AAA1B,kGAAA,OAAO,OAAA;AAChB,uDAAsC;AACtC,gDAA6B;AAC7B,iDAA+C;AAAtC,8GAAA,aAAa,OAAA;AACtB,iCAAuC;AAA9B,8FAAA,KAAK,OAAA;AACd,+BAA6B;AAApB,4FAAA,IAAI,OAAA;AACb,+CAA6C;AAApC,4GAAA,YAAY,OAAA;AACrB,6CAA2C;AAAlC,0GAAA,WAAW,OAAA;AACpB,yCAAoD;AAA3C,sGAAA,SAAS,OAAA;AAAE,wGAAA,WAAW,OAAA;AAC/B,yCAAuC;AAA9B,sGAAA,SAAS,OAAA;AAClB,qDAAoC;AACpC,6DAA2D;AAAlD,0HAAA,mBAAmB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../base/lib/util/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wBAAwB;AACxB,6DAAwD;AAA/C,uHAAA,gBAAgB,OAAA;AACzB,uDAAqD;AAA5C,oHAAA,gBAAgB,OAAA;AACzB,uCAAoB;AAEpB,sDAAsD;AACtD,6DAI8B;AAH5B,0HAAA,mBAAmB,OAAA;AACnB,0HAAA,mBAAmB,OAAA;AACnB,oHAAA,aAAa,OAAA;AAEf,+DAA6D;AAApD,4HAAA,oBAAoB,OAAA;AAC7B,+BAA6B;AAApB,4FAAA,IAAI,OAAA;AACb,qCAAmC;AAA1B,kGAAA,OAAO,OAAA;AAChB,uDAAsC;AACtC,gDAA6B;AAC7B,2DAAyD;AAAhD,wHAAA,kBAAkB,OAAA;AAC3B,iDAA+C;AAAtC,8GAAA,aAAa,OAAA;AACtB,iCAAuC;AAA9B,8FAAA,KAAK,OAAA;AACd,+BAA6B;AAApB,4FAAA,IAAI,OAAA;AACb,+CAA6C;AAApC,4GAAA,YAAY,OAAA;AACrB,6CAA2C;AAAlC,0GAAA,WAAW,OAAA;AACpB,yCAAoD;AAA3C,sGAAA,SAAS,OAAA;AAAE,wGAAA,WAAW,OAAA;AAC/B,yCAAuC;AAA9B,sGAAA,SAAS,OAAA;AAClB,qDAAoC;AACpC,6DAA2D;AAAlD,0HAAA,mBAAmB,OAAA"}

package/base/lib/util/ip.d.ts

@@ -1,30 +1,111 @@
+/**
+ * Represents an IPv4 or IPv6 address as raw octets with arithmetic and comparison operations.
+ *
+ * IPv4 addresses have 4 octets, IPv6 addresses have 16 octets.
+ *
+ * @example
+ * ```ts
+ * const ip = IpAddress.parse("192.168.1.1")
+ * const next = ip.add(1) // 192.168.1.2
+ * ```
+ */
 export declare class IpAddress {
     octets: number[];
     private renderedAddress;
     private renderedOctets;
     protected constructor(octets: number[], renderedAddress: string);
+    /**
+     * Parses an IP address string into an IpAddress instance.
+     * Supports both IPv4 dotted-decimal and IPv6 colon-hex notation (including `::` shorthand).
+     * @param address - The IP address string to parse
+     * @returns A new IpAddress instance
+     * @throws Error if the address format is invalid
+     */
     static parse(address: string): IpAddress;
+    /**
+     * Creates an IpAddress from a raw octet array.
+     * @param octets - Array of 4 octets (IPv4) or 16 octets (IPv6), each 0-255
+     * @returns A new IpAddress instance
+     * @throws Error if the octet array length is not 4 or 16, or any octet exceeds 255
+     */
     static fromOctets(octets: number[]): IpAddress;
+    /** Returns true if this is an IPv4 address (4 octets). */
     isIpv4(): boolean;
+    /** Returns true if this is an IPv6 address (16 octets). */
     isIpv6(): boolean;
+    /** Returns true if this is a public IPv4 address (not in any private range). */
     isPublic(): boolean;
+    /**
+     * Returns a new IpAddress incremented by `n`.
+     * @param n - The integer amount to add (fractional part is truncated)
+     * @returns A new IpAddress with the result
+     * @throws Error on overflow
+     */
     add(n: number): IpAddress;
+    /**
+     * Returns a new IpAddress decremented by `n`.
+     * @param n - The integer amount to subtract (fractional part is truncated)
+     * @returns A new IpAddress with the result
+     * @throws Error on underflow
+     */
     sub(n: number): IpAddress;
+    /**
+     * Compares this address to another, returning -1, 0, or 1.
+     * @param other - An IpAddress instance or string to compare against
+     * @returns -1 if this < other, 0 if equal, 1 if this > other
+     */
     cmp(other: string | IpAddress): -1 | 0 | 1;
+    /** The string representation of this IP address (e.g. `"192.168.1.1"` or `"::1"`). Cached and recomputed only when octets change. */
     get address(): string;
 }
+/**
+ * Represents an IP network (CIDR notation) combining an IP address with a prefix length.
+ * Extends IpAddress with network-specific operations like containment checks and broadcast calculation.
+ *
+ * @example
+ * ```ts
+ * const net = IpNet.parse("192.168.1.0/24")
+ * net.contains("192.168.1.100") // true
+ * net.broadcast() // 192.168.1.255
+ * ```
+ */
 export declare class IpNet extends IpAddress {
     prefix: number;
     private constructor();
+    /**
+     * Creates an IpNet from an IpAddress and prefix length.
+     * @param ip - The base IP address
+     * @param prefix - The CIDR prefix length (0-32 for IPv4, 0-128 for IPv6)
+     * @returns A new IpNet instance
+     * @throws Error if prefix exceeds the address bit length
+     */
     static fromIpPrefix(ip: IpAddress, prefix: number): IpNet;
+    /**
+     * Parses a CIDR notation string (e.g. `"192.168.1.0/24"`) into an IpNet.
+     * @param ipnet - The CIDR string to parse
+     * @returns A new IpNet instance
+     */
     static parse(ipnet: string): IpNet;
+    /**
+     * Checks whether this network contains the given address or subnet.
+     * @param address - An IP address or subnet (string, IpAddress, or IpNet)
+     * @returns True if the address falls within this network's range
+     */
     contains(address: string | IpAddress | IpNet): boolean;
+    /** Returns the network address (all host bits zeroed) for this subnet. */
     zero(): IpAddress;
+    /** Returns the broadcast address (all host bits set to 1) for this subnet. */
     broadcast(): IpAddress;
+    /** The CIDR notation string for this network (e.g. `"192.168.1.0/24"`). */
     get ipnet(): string;
 }
+/** All private IPv4 ranges: loopback (127.0.0.0/8), Class A (10.0.0.0/8), Class B (172.16.0.0/12), Class C (192.168.0.0/16). */
 export declare const PRIVATE_IPV4_RANGES: IpNet[];
+/** IPv4 loopback network (127.0.0.0/8). */
 export declare const IPV4_LOOPBACK: IpNet;
+/** IPv6 loopback address (::1/128). */
 export declare const IPV6_LOOPBACK: IpNet;
+/** IPv6 link-local network (fe80::/10). */
 export declare const IPV6_LINK_LOCAL: IpNet;
+/** Carrier-Grade NAT (CGNAT) address range (100.64.0.0/10), per RFC 6598. */
 export declare const CGNAT: IpNet;

package/base/lib/util/ip.js

@@ -1,12 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CGNAT = exports.IPV6_LINK_LOCAL = exports.IPV6_LOOPBACK = exports.IPV4_LOOPBACK = exports.PRIVATE_IPV4_RANGES = exports.IpNet = exports.IpAddress = void 0;
+/**
+ * Represents an IPv4 or IPv6 address as raw octets with arithmetic and comparison operations.
+ *
+ * IPv4 addresses have 4 octets, IPv6 addresses have 16 octets.
+ *
+ * @example
+ * ```ts
+ * const ip = IpAddress.parse("192.168.1.1")
+ * const next = ip.add(1) // 192.168.1.2
+ * ```
+ */
 class IpAddress {
     constructor(octets, renderedAddress) {
         this.octets = octets;
         this.renderedAddress = renderedAddress;
         this.renderedOctets = [...octets];
     }
+    /**
+     * Parses an IP address string into an IpAddress instance.
+     * Supports both IPv4 dotted-decimal and IPv6 colon-hex notation (including `::` shorthand).
+     * @param address - The IP address string to parse
+     * @returns A new IpAddress instance
+     * @throws Error if the address format is invalid
+     */
     static parse(address) {
         let octets;
         if (address.includes(':')) {
@@ -42,6 +60,12 @@ class IpAddress {
         }
         return new IpAddress(octets, address);
     }
+    /**
+     * Creates an IpAddress from a raw octet array.
+     * @param octets - Array of 4 octets (IPv4) or 16 octets (IPv6), each 0-255
+     * @returns A new IpAddress instance
+     * @throws Error if the octet array length is not 4 or 16, or any octet exceeds 255
+     */
     static fromOctets(octets) {
         if (octets.length == 4) {
             if (octets.some((o) => o > 255)) {
@@ -72,15 +96,24 @@ class IpAddress {
             throw new Error('invalid ip address');
         }
     }
+    /** Returns true if this is an IPv4 address (4 octets). */
     isIpv4() {
         return this.octets.length === 4;
     }
+    /** Returns true if this is an IPv6 address (16 octets). */
     isIpv6() {
         return this.octets.length === 16;
     }
+    /** Returns true if this is a public IPv4 address (not in any private range). */
     isPublic() {
         return this.isIpv4() && !exports.PRIVATE_IPV4_RANGES.some((r) => r.contains(this));
     }
+    /**
+     * Returns a new IpAddress incremented by `n`.
+     * @param n - The integer amount to add (fractional part is truncated)
+     * @returns A new IpAddress with the result
+     * @throws Error on overflow
+     */
     add(n) {
         let octets = [...this.octets];
         n = Math.floor(n);
@@ -99,6 +132,12 @@ class IpAddress {
         }
         return IpAddress.fromOctets(octets);
     }
+    /**
+     * Returns a new IpAddress decremented by `n`.
+     * @param n - The integer amount to subtract (fractional part is truncated)
+     * @returns A new IpAddress with the result
+     * @throws Error on underflow
+     */
     sub(n) {
         let octets = [...this.octets];
         n = Math.floor(n);
@@ -117,6 +156,11 @@ class IpAddress {
         }
         return IpAddress.fromOctets(octets);
     }
+    /**
+     * Compares this address to another, returning -1, 0, or 1.
+     * @param other - An IpAddress instance or string to compare against
+     * @returns -1 if this < other, 0 if equal, 1 if this > other
+     */
     cmp(other) {
         if (typeof other === 'string')
             other = IpAddress.parse(other);
@@ -133,6 +177,7 @@ class IpAddress {
         }
         return 0;
     }
+    /** The string representation of this IP address (e.g. `"192.168.1.1"` or `"::1"`). Cached and recomputed only when octets change. */
     get address() {
         if (this.renderedOctets.length === this.octets.length &&
             this.renderedOctets.every((o, idx) => o === this.octets[idx])) {
@@ -169,23 +214,51 @@ class IpAddress {
     }
 }
 exports.IpAddress = IpAddress;
+/**
+ * Represents an IP network (CIDR notation) combining an IP address with a prefix length.
+ * Extends IpAddress with network-specific operations like containment checks and broadcast calculation.
+ *
+ * @example
+ * ```ts
+ * const net = IpNet.parse("192.168.1.0/24")
+ * net.contains("192.168.1.100") // true
+ * net.broadcast() // 192.168.1.255
+ * ```
+ */
 class IpNet extends IpAddress {
     constructor(octets, prefix, address) {
         super(octets, address);
         this.prefix = prefix;
     }
+    /**
+     * Creates an IpNet from an IpAddress and prefix length.
+     * @param ip - The base IP address
+     * @param prefix - The CIDR prefix length (0-32 for IPv4, 0-128 for IPv6)
+     * @returns A new IpNet instance
+     * @throws Error if prefix exceeds the address bit length
+     */
     static fromIpPrefix(ip, prefix) {
         if (prefix > ip.octets.length * 8) {
             throw new Error('invalid prefix');
         }
         return new IpNet(ip.octets, prefix, ip.address);
     }
+    /**
+     * Parses a CIDR notation string (e.g. `"192.168.1.0/24"`) into an IpNet.
+     * @param ipnet - The CIDR string to parse
+     * @returns A new IpNet instance
+     */
     static parse(ipnet) {
         const [address, prefixStr] = ipnet.split('/', 2);
         const ip = IpAddress.parse(address);
         const prefix = Number(prefixStr);
         return IpNet.fromIpPrefix(ip, prefix);
     }
+    /**
+     * Checks whether this network contains the given address or subnet.
+     * @param address - An IP address or subnet (string, IpAddress, or IpNet)
+     * @returns True if the address falls within this network's range
+     */
     contains(address) {
         if (typeof address === 'string')
             address = IpAddress.parse(address);
@@ -207,6 +280,7 @@ class IpNet extends IpAddress {
         const mask = 255 ^ (255 >> prefix);
         return (this.octets[idx] & mask) === (address.octets[idx] & mask);
     }
+    /** Returns the network address (all host bits zeroed) for this subnet. */
     zero() {
         let octets = [];
         let prefix = this.prefix;
@@ -223,6 +297,7 @@ class IpNet extends IpAddress {
         }
         return IpAddress.fromOctets(octets);
     }
+    /** Returns the broadcast address (all host bits set to 1) for this subnet. */
     broadcast() {
         let octets = [];
         let prefix = this.prefix;
@@ -239,19 +314,25 @@ class IpNet extends IpAddress {
         }
         return IpAddress.fromOctets(octets);
     }
+    /** The CIDR notation string for this network (e.g. `"192.168.1.0/24"`). */
     get ipnet() {
         return `${this.address}/${this.prefix}`;
     }
 }
 exports.IpNet = IpNet;
+/** All private IPv4 ranges: loopback (127.0.0.0/8), Class A (10.0.0.0/8), Class B (172.16.0.0/12), Class C (192.168.0.0/16). */
 exports.PRIVATE_IPV4_RANGES = [
     IpNet.parse('127.0.0.0/8'),
     IpNet.parse('10.0.0.0/8'),
     IpNet.parse('172.16.0.0/12'),
     IpNet.parse('192.168.0.0/16'),
 ];
+/** IPv4 loopback network (127.0.0.0/8). */
 exports.IPV4_LOOPBACK = IpNet.parse('127.0.0.0/8');
+/** IPv6 loopback address (::1/128). */
 exports.IPV6_LOOPBACK = IpNet.parse('::1/128');
+/** IPv6 link-local network (fe80::/10). */
 exports.IPV6_LINK_LOCAL = IpNet.parse('fe80::/10');
+/** Carrier-Grade NAT (CGNAT) address range (100.64.0.0/10), per RFC 6598. */
 exports.CGNAT = IpNet.parse('100.64.0.0/10');
 //# sourceMappingURL=ip.js.map