@start9labs/start-sdk 0.4.0-beta.9 → 0.4.0

package/base/lib/util/getDefaultString.js

@@ -2,8 +2,16 @@
 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") {
+    if (typeof defaultSpec === 'string') {
         return defaultSpec;
     }
     else {

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/getRandomCharInSet.js

@@ -11,7 +11,7 @@ function getRandomCharInSet(charset) {
         }
         charIdx -= range.len;
     }
-    throw new Error("unreachable");
+    throw new Error('unreachable');
 }
 function stringToCharSet(charset) {
     let set = { ranges: [], len: 0 };
@@ -20,10 +20,10 @@ function stringToCharSet(charset) {
     let in_range = false;
     for (let char of charset) {
         switch (char) {
-            case ",":
+            case ',':
                 if (start !== null && end !== null) {
                     if (start.charCodeAt(0) > end.charCodeAt(0)) {
-                        throw new Error("start > end of charset");
+                        throw new Error('start > end of charset');
                     }
                     const len = end.charCodeAt(0) - start.charCodeAt(0) + 1;
                     set.ranges.push({
@@ -42,24 +42,24 @@ function stringToCharSet(charset) {
                     start = null;
                 }
                 else if (start !== null && in_range) {
-                    end = ",";
+                    end = ',';
                 }
                 else if (start === null && end === null && !in_range) {
-                    start = ",";
+                    start = ',';
                 }
                 else {
                     throw new Error('unexpected ","');
                 }
                 break;
-            case "-":
+            case '-':
                 if (start === null) {
-                    start = "-";
+                    start = '-';
                 }
                 else if (!in_range) {
                     in_range = true;
                 }
                 else if (in_range && end === null) {
-                    end = "-";
+                    end = '-';
                 }
                 else {
                     throw new Error('unexpected "-"');
@@ -79,7 +79,7 @@ function stringToCharSet(charset) {
     }
     if (start !== null && end !== null) {
         if (start.charCodeAt(0) > end.charCodeAt(0)) {
-            throw new Error("start > end of charset");
+            throw new Error('start > end of charset');
         }
         const len = end.charCodeAt(0) - start.charCodeAt(0) + 1;
         set.ranges.push({

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

@@ -1,2 +1,2 @@
-import { RandomString } from "../actions/input/inputSpecTypes";
+import { RandomString } from '../actions/input/inputSpecTypes';
 export declare function getRandomString(generator: RandomString): string;

package/base/lib/util/getRandomString.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRandomString = getRandomString;
 const getRandomCharInSet_1 = require("./getRandomCharInSet");
 function getRandomString(generator) {
-    let s = "";
+    let s = '';
     for (let i = 0; i < generator.len; i++) {
         s = s + (0, getRandomCharInSet_1.getRandomCharInSet)(generator.charset);
     }

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

@@ -1,35 +1,138 @@
-import { ServiceInterfaceType } from "../types";
-import { AddressInfo, Host, Hostname, HostnameInfo } from "../types";
-import { Effects } from "../Effects";
+import { PackageId, ServiceInterfaceId, ServiceInterfaceType } from '../types';
+import { AddressInfo, Host, Hostname, HostnameInfo } from '../types';
+import { Effects } from '../Effects';
+import { Watchable } from './Watchable';
 export type UrlString = string;
 export type HostId = string;
 export declare const getHostname: (url: string) => Hostname | null;
-type FilterKinds = "onion" | "local" | "domain" | "ip" | "ipv4" | "ipv6";
+/**
+ * The kinds of hostnames that can be filtered on.
+ *
+ * - `'mdns'` — mDNS / Bonjour `.local` hostnames
+ * - `'domain'` — any os-managed domain name (matches both `'private-domain'` and `'public-domain'` metadata kinds)
+ * - `'ip'` — shorthand for both `'ipv4'` and `'ipv6'`
+ * - `'ipv4'` — IPv4 addresses only
+ * - `'ipv6'` — IPv6 addresses only
+ * - `'localhost'` — loopback addresses (`localhost`, `127.0.0.1`, `::1`)
+ * - `'link-local'` — IPv6 link-local addresses (fe80::/10)
+ * - `'bridge'` — The LXC bridge interface
+ * - `'plugin'` — hostnames provided by a plugin package
+ */
+type FilterKinds = 'mdns' | 'domain' | 'ip' | 'ipv4' | 'ipv6' | 'localhost' | 'link-local' | 'bridge' | 'plugin';
+/**
+ * Describes which hostnames to include (or exclude) when filtering a `Filled` address.
+ *
+ * Every field is optional — omitted fields impose no constraint.
+ * Filters are composable: the `.filter()` method intersects successive filters,
+ * and the `exclude` field inverts a nested filter.
+ */
 export type Filter = {
-    visibility?: "public" | "private";
+    /** Keep only hostnames with the given visibility. `'public'` = externally reachable, `'private'` = LAN-only. */
+    visibility?: 'public' | 'private';
+    /** Keep only hostnames whose metadata kind matches. A single kind or array of kinds. `'ip'` expands to `['ipv4','ipv6']`, `'domain'` matches both `'private-domain'` and `'public-domain'`. */
     kind?: FilterKinds | FilterKinds[];
+    /** Arbitrary predicate — hostnames for which this returns `false` are excluded. */
+    predicate?: (h: HostnameInfo) => boolean;
+    /** Keep only plugin hostnames provided by this package. Implies `kind: 'plugin'`. */
+    pluginId?: PackageId;
+    /** A nested filter whose matches are *removed* from the result (logical NOT). */
     exclude?: Filter;
 };
-type Formats = "hostname-info" | "urlstring" | "url";
-type FormatReturnTy<Format extends Formats> = Format extends "hostname-info" ? HostnameInfo : Format extends "url" ? URL : UrlString;
-export type Filled = {
+type VisibilityFilter<V extends 'public' | 'private'> = V extends 'public' ? (HostnameInfo & {
+    public: true;
+}) | VisibilityFilter<Exclude<V, 'public'>> : V extends 'private' ? (HostnameInfo & {
+    public: false;
+}) | VisibilityFilter<Exclude<V, 'private'>> : never;
+type KindFilter<K extends FilterKinds> = K extends 'mdns' ? (HostnameInfo & {
+    metadata: {
+        kind: 'mdns';
+    };
+}) | KindFilter<Exclude<K, 'mdns'>> : K extends 'domain' ? (HostnameInfo & {
+    metadata: {
+        kind: 'private-domain';
+    };
+}) | (HostnameInfo & {
+    metadata: {
+        kind: 'public-domain';
+    };
+}) | KindFilter<Exclude<K, 'domain'>> : K extends 'ipv4' ? (HostnameInfo & {
+    metadata: {
+        kind: 'ipv4';
+    };
+}) | KindFilter<Exclude<K, 'ipv4'>> : K extends 'ipv6' ? (HostnameInfo & {
+    metadata: {
+        kind: 'ipv6';
+    };
+}) | KindFilter<Exclude<K, 'ipv6'>> : K extends 'plugin' ? (HostnameInfo & {
+    metadata: {
+        kind: 'plugin';
+    };
+}) | KindFilter<Exclude<K, 'plugin'>> : K extends 'ip' ? KindFilter<Exclude<K, 'ip'> | 'ipv4' | 'ipv6'> : never;
+type FilterReturnTy<F extends Filter> = F extends {
+    visibility: infer V extends 'public' | 'private';
+} ? VisibilityFilter<V> & FilterReturnTy<Omit<F, 'visibility'>> : F extends {
+    kind: (infer K extends FilterKinds) | (infer K extends FilterKinds)[];
+} ? KindFilter<K> & FilterReturnTy<Omit<F, 'kind'>> : F extends {
+    predicate: (h: HostnameInfo) => h is infer H extends HostnameInfo;
+} ? H & FilterReturnTy<Omit<F, 'predicate'>> : F extends {
+    exclude: infer E extends Filter;
+} ? HostnameInfo extends FilterReturnTy<E> ? HostnameInfo : Exclude<HostnameInfo, FilterReturnTy<E>> : HostnameInfo;
+declare const nonLocalFilter: {
+    readonly exclude: {
+        readonly kind: ("localhost" | "link-local" | "bridge")[];
+    };
+};
+declare const publicFilter: {
+    readonly visibility: "public";
+};
+type Formats = 'hostname-info' | 'urlstring' | 'url';
+type FormatReturnTy<F extends Filter, Format extends Formats> = Format extends 'hostname-info' ? FilterReturnTy<F> | FormatReturnTy<F, Exclude<Format, 'hostname-info'>> : Format extends 'url' ? URL | FormatReturnTy<F, Exclude<Format, 'url'>> : Format extends 'urlstring' ? UrlString | FormatReturnTy<F, Exclude<Format, 'urlstring'>> : never;
+/**
+ * A resolved address with its hostnames already populated, plus helpers
+ * for filtering, formatting, and converting hostnames to URLs.
+ *
+ * Filters are chainable and each call returns a new `Filled` narrowed to the
+ * matching subset of hostnames:
+ *
+ * ```ts
+ * addresses.nonLocal                         // exclude localhost & link-local
+ * addresses.public                           // only publicly-reachable hostnames
+ * addresses.filter({ kind: 'domain' })       // only domain-name hostnames
+ * addresses.filter({ visibility: 'private' }) // only LAN-reachable hostnames
+ * addresses.nonLocal.filter({ kind: 'ip' })  // chainable — non-local IPs only
+ * ```
+ */
+export type Filled<F extends Filter = {}> = {
+    /** The hostnames that survived all applied filters. */
     hostnames: HostnameInfo[];
-    filter: <Format extends Formats = "urlstring">(filter: Filter, format?: Format) => FormatReturnTy<Format>[];
-    publicHostnames: HostnameInfo[];
-    onionHostnames: HostnameInfo[];
-    localHostnames: HostnameInfo[];
-    ipHostnames: HostnameInfo[];
-    ipv4Hostnames: HostnameInfo[];
-    ipv6Hostnames: HostnameInfo[];
-    nonIpHostnames: HostnameInfo[];
-    urls: UrlString[];
-    publicUrls: UrlString[];
-    onionUrls: UrlString[];
-    localUrls: UrlString[];
-    ipUrls: UrlString[];
-    ipv4Urls: UrlString[];
-    ipv6Urls: UrlString[];
-    nonIpUrls: UrlString[];
+    /** Convert a single hostname into a fully-formed URL string, applying the address's scheme, username, and suffix. */
+    toUrl: (h: HostnameInfo) => UrlString;
+    /**
+     * Return every hostname in the requested format.
+     *
+     * - `'urlstring'` (default) — formatted URL strings
+     * - `'url'`                 — `URL` objects
+     * - `'hostname-info'`       — raw `HostnameInfo` objects
+     */
+    format: <Format extends Formats = 'urlstring'>(format?: Format) => FormatReturnTy<{}, Format>[];
+    /**
+     * Apply an arbitrary {@link Filter} and return a new `Filled` containing only
+     * the hostnames that match. Filters compose: calling `.filter()` on an
+     * already-filtered `Filled` intersects the constraints.
+     */
+    filter: <NewFilter extends Filter>(filter: NewFilter) => Filled<NewFilter & Filter>;
+    /**
+     * Apply multiple filters and return hostnames that match **any** of them (union / OR).
+     *
+     * ```ts
+     * addresses.matchesAny([{ kind: 'domain' }, { kind: 'mdns' }])
+     * ```
+     */
+    matchesAny: <NewFilters extends Filter[]>(filters: [...NewFilters]) => Filled<NewFilters[number] & F>;
+    /** Shorthand filter that excludes `localhost` and IPv6 link-local addresses — keeps only network-reachable hostnames. */
+    nonLocal: Filled<typeof nonLocalFilter & Filter>;
+    /** Shorthand filter that keeps only publicly-reachable hostnames (those with `public: true`). */
+    public: Filled<typeof publicFilter & Filter>;
 };
 export type FilledAddressInfo = AddressInfo & Filled;
 export type ServiceInterfaceFilled = {
@@ -47,37 +150,36 @@ export type ServiceInterfaceFilled = {
     /** Indicates if we are a ui/p2p/api for the kind of interface that this is representing */
     type: ServiceInterfaceType;
 };
-export declare const addressHostToUrl: ({ scheme, sslScheme, username, suffix }: AddressInfo, host: HostnameInfo) => UrlString[];
+export declare const addressHostToUrl: ({ scheme, sslScheme, username, suffix }: AddressInfo, hostname: HostnameInfo) => UrlString;
+/**
+ * Filters out localhost and IPv6 link-local hostnames from a list.
+ * Equivalent to the `nonLocal` filter on `Filled` addresses.
+ */
+export declare function filterNonLocal(hostnames: HostnameInfo[]): HostnameInfo[];
 export declare const filledAddress: (host: Host, addressInfo: AddressInfo) => FilledAddressInfo;
-export declare class GetServiceInterface {
-    readonly effects: Effects;
+export declare class GetServiceInterface<Mapped = ServiceInterfaceFilled | null> extends Watchable<ServiceInterfaceFilled | null, Mapped> {
     readonly opts: {
         id: string;
         packageId?: string;
     };
+    protected readonly label = "GetServiceInterface";
     constructor(effects: Effects, opts: {
         id: string;
         packageId?: string;
+    }, options?: {
+        map?: (value: ServiceInterfaceFilled | null) => Mapped;
+        eq?: (a: Mapped, b: Mapped) => boolean;
     });
-    /**
-     * Returns the requested service interface. Reruns the context from which it has been called if the underlying value changes
-     */
-    const(): Promise<ServiceInterfaceFilled | null>;
-    /**
-     * Returns the requested service interface. Does nothing if the value changes
-     */
-    once(): Promise<ServiceInterfaceFilled | null>;
-    /**
-     * Watches the requested service interface. Returns an async iterator that yields whenever the value changes
-     */
-    watch(): AsyncGenerator<ServiceInterfaceFilled | null, void, unknown>;
-    /**
-     * Watches the requested service interface. Takes a custom callback function to run whenever the value changes
-     */
-    onChange(callback: (value: ServiceInterfaceFilled | null, error?: Error) => void | Promise<void>): void;
+    protected fetch(callback?: () => void): Promise<ServiceInterfaceFilled | null>;
 }
+export declare function getOwnServiceInterface(effects: Effects, id: ServiceInterfaceId): GetServiceInterface;
+export declare function getOwnServiceInterface<Mapped>(effects: Effects, id: ServiceInterfaceId, map: (interfaces: ServiceInterfaceFilled | null) => Mapped, eq?: (a: Mapped, b: Mapped) => boolean): GetServiceInterface<Mapped>;
 export declare function getServiceInterface(effects: Effects, opts: {
-    id: string;
-    packageId?: string;
+    id: ServiceInterfaceId;
+    packageId: PackageId;
 }): GetServiceInterface;
+export declare function getServiceInterface<Mapped>(effects: Effects, opts: {
+    id: ServiceInterfaceId;
+    packageId: PackageId;
+}, map: (interfaces: ServiceInterfaceFilled | null) => Mapped, eq?: (a: Mapped, b: Mapped) => boolean): GetServiceInterface<Mapped>;
 export {};