@dbx-tools/shared-core 0.3.44 → 0.4.0

package/lib/src/net.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Browser-safe networking helpers built around {@link urlBuilder}: a
+ * tolerant `URL` coercion + chainable builder that gracefully handles
+ * partial inputs (bare hosts, path-only strings, `{ url }` wrappers),
+ * a small IPv4 / IPv6 address + CIDR toolkit (parsing and membership
+ * lookups), and email-address parsing ({@link parseEmails} /
+ * {@link isEmail}) that normalizes the CSV / single-string / array
+ * inputs email recipient and allow-list fields accept into a clean
+ * `string[]`. No node-only imports, so this module is the canonical
+ * home for anything URL-, IP-, or email-shaped that also has to run in
+ * a Vite / Webpack / esbuild client bundle. Node-only network helpers
+ * (e.g. DNS resolution) belong in a node-tagged package, not here.
+ *
+ * @module
+ */
+import type { NonFunctionKeys } from "./object.js";
+/**
+ * Anything {@link urlBuilder} (and {@link pathMatch}) know how to coerce
+ * into a URL:
+ *
+ * - A string: a host, a full URL, or a path / query / hash fragment.
+ * - A WHATWG `URL` instance.
+ * - Any object with a `url` field (e.g. a fetch `Request`, a Databricks
+ *   `WorkspaceClient` config).
+ */
+export type UrlLike = string | URL | {
+    url: string;
+};
+/** IP protocol family: `4` for IPv4, `6` for IPv6. */
+export type IpVersion = 4 | 6;
+/**
+ * A parsed IP address. `value` is the address as an unsigned integer
+ * (a 32-bit range for v4, 128-bit for v6) held in a `bigint` so both
+ * families share one comparison / masking path. Produce one with
+ * {@link parseIp}.
+ */
+export interface ParsedIp {
+    version: IpVersion;
+    /** The address as an unsigned integer (`bigint` for uniform v4/v6 math). */
+    value: bigint;
+}
+/**
+ * A parsed CIDR block (`10.0.0.0/8`, `2001:db8::/32`). `base` is the
+ * network address with all host bits cleared, so membership is a
+ * single masked compare (see {@link ipInCidr}). Produce one with
+ * {@link parseCidr}. Carries the normalized `cidr` string for logging
+ * and to key back to caller-side metadata.
+ */
+export interface Cidr {
+    version: IpVersion;
+    /** Network address (host bits zeroed) as an unsigned `bigint`. */
+    base: bigint;
+    /** Prefix length in bits (the number after the `/`). */
+    prefix: number;
+    /** Normalized `<address>/<prefix>` string. */
+    cidr: string;
+}
+/** Settable, non-method `URL` properties - the keys {@link UrlBuilder.with} accepts. */
+type UrlPropertyKey = NonFunctionKeys<UrlBuilderImpl>;
+/**
+ * A `URL` subclass with chainable, copy-on-write helpers. Every mutating
+ * method returns a fresh builder rather than editing in place, so a base
+ * builder can be safely reused. Construct one via {@link urlBuilder}.
+ */
+declare class UrlBuilderImpl extends URL {
+    constructor(url: URL);
+    /** The scheme without the trailing colon (`https`, not `https:`). */
+    get scheme(): string;
+    set scheme(value: string);
+    /**
+     * Return a copy with a single `URL` property (`pathname`, `search`,
+     * `hostname`, `scheme`, ...) set to `value`, leaving this builder
+     * untouched.
+     */
+    with<K extends UrlPropertyKey>(key: K, value: UrlBuilderImpl[K]): UrlBuilder;
+    /**
+     * Return a copy with `pathSegments` appended to the current pathname.
+     * Segments may be strings or string arrays; each is trimmed of
+     * boundary slashes and blanks are dropped before joining with `/`.
+     */
+    withPathAppend(...pathSegments: (string | string[])[]): UrlBuilder;
+    /**
+     * Return a copy whose pathname is `pathSegments` joined with `/`,
+     * replacing any existing path. Segments may be strings or string
+     * arrays; each is trimmed of boundary slashes and blanks are dropped.
+     */
+    withPathReplace(...pathSegments: (string | string[])[]): UrlBuilder;
+    /**
+     * Test whether this URL's pathname is `path` or lives beneath it,
+     * matching on segment boundaries so `/api` matches `/api` and
+     * `/api/cool` but not `/apicool`. A missing leading slash on `path`
+     * is tolerated; query and hash are ignored (they aren't part of
+     * `pathname`). Matching is exact otherwise - trailing slashes are
+     * not normalized and `/` matches only the root.
+     */
+    pathMatches(path: string): boolean;
+}
+/** Public type for the {@link urlBuilder} return value. */
+export type UrlBuilder = UrlBuilderImpl;
+/** With no argument, resolves to the base origin (never `null`). */
+export declare function urlBuilder(): UrlBuilder;
+/**
+ * Coerce a {@link UrlLike} into a chainable {@link UrlBuilder}, or `null`
+ * when the input cannot be parsed into a URL. Never throws.
+ *
+ * - A `URL` instance or `{ url }` wrapper is adopted as-is.
+ * - A bare hostname (`"example.com"`) is upgraded to `https://`; an
+ *   explicit scheme is preserved.
+ * - A path / query / hash fragment (`"/api"`, `"?q=1"`, `"#x"`) is
+ *   resolved against {@link defaultUrl} (the browser origin, else
+ *   `http://localhost`).
+ * - An empty / blank string or omitted input resolves to the base
+ *   origin.
+ *
+ * @example
+ * urlBuilder("example.com");          // https://example.com/
+ * urlBuilder("http://x/path");        // http://x/path
+ * urlBuilder("/api/v2");              // http://localhost/api/v2
+ * urlBuilder({ url: "http://y" });    // http://y/
+ * urlBuilder();                       // http://localhost/
+ */
+export declare function urlBuilder(input?: UrlLike): UrlBuilder | undefined;
+/**
+ * Convenience wrapper over {@link UrlBuilder.pathMatches}: coerce
+ * `input` via {@link urlBuilder} and test its pathname against `path`.
+ * Returns `false` for input that can't be parsed into a URL.
+ *
+ * @example
+ * pathMatch("/api/cool?q=1", "/api");      // true
+ * pathMatch("/apicool", "/api");           // false
+ * pathMatch("https://host/api", "/api");   // true
+ * pathMatch(request, "/api/v2");           // fetch Request
+ */
+export declare function pathMatch(input: UrlLike, path: string): boolean;
+/** Options for {@link parseEmails}. */
+export interface ParseEmailsOptions {
+    /** Lower-case every address (useful for allow-lists / matching). Off by default. */
+    lowercase?: boolean;
+    /**
+     * Drop later case-insensitive duplicates, keeping first-seen casing.
+     * On by default - a recipient or pattern list rarely wants repeats.
+     */
+    dedupe?: boolean;
+}
+/**
+ * Normalize the shapes an email address field accepts - a single string,
+ * a comma / semicolon / whitespace separated list, an array of either,
+ * or nothing - into a clean `string[]`. Each entry is split on the list
+ * separators, trimmed, and de-emptied; blanks and non-string array
+ * members are dropped. By default duplicates are removed
+ * case-insensitively (first-seen casing wins) and casing is otherwise
+ * preserved; pass `lowercase` to fold everything to lower case (e.g. for
+ * an allow-list). This is the one place recipient lists, CC/BCC inputs,
+ * and sender allow-lists across the repo agree on how free-text email
+ * input is read. Never throws; does not validate - pair with
+ * {@link isEmail} when you need to reject malformed addresses.
+ *
+ * @example
+ * parseEmails("a@x.com, b@y.com; a@x.com"); // ["a@x.com", "b@y.com"]
+ * parseEmails(["A@x.com", " b@y.com "]);      // ["A@x.com", "b@y.com"]
+ * parseEmails("*@corp.com", { lowercase: true }); // ["*@corp.com"]
+ * parseEmails(undefined);                     // []
+ */
+export declare function parseEmails(input: string | readonly string[] | null | undefined, options?: ParseEmailsOptions): string[];
+/**
+ * Pragmatic `local@domain.tld` shape check: non-empty local and domain
+ * parts around a single `@`, with a dotted domain and no whitespace.
+ * Deliberately loose (not full RFC 5322) - enough to catch obvious typos
+ * and give CLI / form feedback, not to gate delivery. Trims first. This
+ * is a purely syntactic test, so a wildcard allow-list pattern like
+ * `*@example.com` passes; distinguishing a pattern from a real address
+ * is the sender policy's job, not this validator's.
+ *
+ * @example
+ * isEmail("alice@example.com"); // true
+ * isEmail("nope");              // false (no @)
+ * isEmail("no@domain");         // false (no dotted domain)
+ */
+export declare function isEmail(value: string): boolean;
+/**
+ * Parse an IPv4 (`"1.2.3.4"`) or IPv6 (`"2001:db8::1"`,
+ * `"::ffff:1.2.3.4"`, `"::1"`) address into a {@link ParsedIp}, or
+ * `null` when the input isn't a valid literal. Never throws. Surrounding
+ * whitespace, `[...]` brackets around an IPv6 literal, and an IPv6 zone
+ * id (`fe80::1%eth0`) are all tolerated. The `value` is returned as a
+ * `bigint` so v4 and v6 share one comparison path.
+ *
+ * @example
+ * parseIp("10.0.0.1");        // { version: 4, value: 167772161n }
+ * parseIp("2001:db8::1");     // { version: 6, value: ... }
+ * parseIp("not-an-ip");       // null
+ */
+export declare function parseIp(input: string): ParsedIp | null;
+/**
+ * Parse a CIDR block (`"10.0.0.0/8"`, `"2001:db8::/32"`) into a
+ * {@link Cidr} with host bits cleared from `base`, or `null` when the
+ * input isn't a valid block (bad address, missing / out-of-range
+ * prefix). Never throws.
+ *
+ * @example
+ * parseCidr("10.0.0.0/8")?.base;   // 167772160n (10.0.0.0)
+ * parseCidr("10.1.2.3/8")?.base;   // 167772160n (host bits dropped)
+ * parseCidr("10.0.0.0/40");        // null (prefix > 32 for v4)
+ */
+export declare function parseCidr(input: string): Cidr | null;
+/**
+ * Test whether `ip` falls inside `cidr`. Both arguments accept either
+ * a string (parsed on the fly via {@link parseIp} / {@link parseCidr})
+ * or an already-parsed value - pass parsed values in hot loops to skip
+ * re-parsing. Returns `false` for unparseable input or a version
+ * mismatch (an IPv4 address is never inside an IPv6 block).
+ *
+ * @example
+ * ipInCidr("10.1.2.3", "10.0.0.0/8");   // true
+ * ipInCidr("11.0.0.1", "10.0.0.0/8");   // false
+ */
+export declare function ipInCidr(ip: string | ParsedIp, cidr: string | Cidr): boolean;
+/**
+ * Return the first CIDR in `cidrs` that contains `ip`, or `null` when
+ * none match. `cidrs` holds pre-parsed {@link Cidr} values (or any
+ * object extending it), so callers can carry side metadata on each
+ * entry (e.g. a region tag) and read it straight off the returned
+ * match. Linear scan; parse the address once by passing a
+ * {@link ParsedIp}.
+ *
+ * @example
+ * const ranges = ["10.0.0.0/8", "192.168.0.0/16"]
+ *   .map(parseCidr)
+ *   .filter((c): c is Cidr => c !== null);
+ * findContainingCidr("10.1.2.3", ranges)?.cidr; // "10.0.0.0/8"
+ */
+export declare function findContainingCidr<T extends Cidr>(ip: string | ParsedIp, cidrs: Iterable<T>): T | null;
+/**
+ * Whether `input`'s host is a loopback address - `localhost`, an IPv4
+ * `127.0.0.0/8` address, or IPv6 `::1` - i.e. a service running on this
+ * machine (e.g. a local registry). Accepts anything {@link urlBuilder}
+ * coerces (a URL string, `URL`, or `{ url }`); returns `false` when the
+ * input has no resolvable host.
+ *
+ * @example
+ * isLoopbackHost("http://localhost:4873"); // true
+ * isLoopbackHost("http://127.0.0.1");       // true
+ * isLoopbackHost("https://registry.npmjs.org"); // false
+ */
+export declare function isLoopbackHost(input: UrlLike): boolean;
+export {};