@depthbomb/common 2.0.0 → 2.2.0

package/dist/url.d.cts

@@ -1,6 +1,15 @@
 //#region src/url.d.ts
+/**
+ * Values accepted by {@link URLPath} constructors and helpers.
+ */
 type URLLike = string | URL | URLPath;
+/**
+ * A single query parameter value (including nested and array values).
+ */
 type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
+/**
+ * Query-object shape used by URL query mutation helpers.
+ */
 type QueryObject = Record<string, QueryValue | QueryValue[]>;
 /**
  * Tagged-template helper for encoded URL path segments.
@@ -9,44 +18,186 @@ type QueryObject = Record<string, QueryValue | QueryValue[]>;
  * const path = url`/users/${userId}/posts/${postId}`;
  */
 declare function url(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Immutable URL utility wrapper with convenience path/query operations.
+ */
 declare class URLPath {
   #private;
+  /**
+   * Creates a `URLPath` from a URL-like input and optional base URL.
+   *
+   * @param input URL value to parse.
+   * @param base Optional base URL for relative inputs.
+   */
   constructor(input: URLLike, base?: URLLike);
+  /**
+   * URL protocol including trailing `:`.
+   */
   get protocol(): string;
+  /**
+   * Host including port when present.
+   */
   get host(): string;
+  /**
+   * Hostname without port.
+   */
   get hostname(): string;
+  /**
+   * Port component, or an empty string when absent.
+   */
   get port(): string;
+  /**
+   * URL origin (`protocol + // + host`).
+   */
   get origin(): string;
+  /**
+   * Username component.
+   */
   get username(): string;
+  /**
+   * Password component.
+   */
   get password(): string;
+  /**
+   * Hash fragment including leading `#` when present.
+   */
   get hash(): string;
+  /**
+   * Search component including leading `?` when present.
+   */
   get search(): string;
+  /**
+   * Returns a copy of query parameters.
+   */
   get searchParams(): URLSearchParams;
+  /**
+   * URL pathname component.
+   */
   get pathname(): string;
+  /**
+   * Decoded pathname segments without empty parts.
+   */
   get parts(): string[];
+  /**
+   * Final path segment (decoded).
+   */
   get name(): string;
+  /**
+   * File suffix from {@link name}, including the leading dot.
+   */
   get suffix(): string;
+  /**
+   * File name without suffix from {@link name}.
+   */
   get stem(): string;
+  /**
+   * Parent path with the last path segment removed.
+   */
   get parent(): URLPath;
+  /**
+   * Appends path segments and returns a new URL.
+   *
+   * @param segments Segments to append.
+   */
   joinpath(...segments: string[]): URLPath;
+  /**
+   * Alias of {@link joinpath}.
+   *
+   * @param segments Segments to append.
+   */
   div(...segments: string[]): URLPath;
+  /**
+   * Creates a copy with replaced pathname parts.
+   *
+   * @param parts Decoded path parts.
+   */
   private withPath;
+  /**
+   * Replaces query parameter values for the provided keys.
+   *
+   * @param params Query values to set.
+   */
   withQuery(params: QueryObject): URLPath;
+  /**
+   * Alias of {@link withQuery}.
+   *
+   * @param params Query values to set.
+   */
   withQueryPatch(params: QueryObject): URLPath;
+  /**
+   * Appends query parameter values without deleting existing values.
+   *
+   * @param params Query values to append.
+   */
   appendQuery(params: QueryObject): URLPath;
+  /**
+   * Removes query keys whose values are entirely empty strings.
+   */
   withoutEmptyQuery(): URLPath;
+  /**
+   * Removes selected query keys.
+   *
+   * @param keys Query keys to remove.
+   */
   withoutQuery(...keys: string[]): URLPath;
+  /**
+   * Sets the hash fragment and returns a new URL.
+   *
+   * @param hash Hash value with or without leading `#`.
+   */
   withHash(hash: string): URLPath;
+  /**
+   * Removes the hash fragment.
+   */
   withoutHash(): URLPath;
+  /**
+   * Calls global `fetch` with this URL as input.
+   *
+   * @param init Optional fetch options.
+   */
   fetch(init?: RequestInit): Promise<Response>;
+  /**
+   * Resolves a relative URL against this URL.
+   *
+   * @param relative Relative URL/path.
+   */
   resolve(relative: string): URLPath;
+  /**
+   * Compares URLs by normalized string value.
+   *
+   * @param other URL to compare.
+   */
   equals(other: URLLike): boolean;
+  /**
+   * Returns a new native `URL` instance.
+   */
   toURL(): URL;
+  /**
+   * Returns the URL as a string.
+   */
   toString(): string;
+  /**
+   * Primitive value representation.
+   */
   valueOf(): string;
+  /**
+   * Primitive coercion hook.
+   */
   [Symbol.toPrimitive](): string;
+  /**
+   * Creates a `URLPath` from URL-like input.
+   *
+   * @param input URL value to parse.
+   * @param base Optional base URL for relative inputs.
+   */
   static from(input: URLLike, base?: URLLike): URLPath;
+  /**
+   * Parses an absolute URL string.
+   *
+   * @param input URL string to parse.
+   */
   static parse(input: string): URLPath;
+  private appendQueryValue;
 }
 //#endregion
 export { QueryObject, QueryValue, URLLike, URLPath, url };

package/dist/url.d.mts

@@ -1,6 +1,15 @@
 //#region src/url.d.ts
+/**
+ * Values accepted by {@link URLPath} constructors and helpers.
+ */
 type URLLike = string | URL | URLPath;
+/**
+ * A single query parameter value (including nested and array values).
+ */
 type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
+/**
+ * Query-object shape used by URL query mutation helpers.
+ */
 type QueryObject = Record<string, QueryValue | QueryValue[]>;
 /**
  * Tagged-template helper for encoded URL path segments.
@@ -9,44 +18,186 @@ type QueryObject = Record<string, QueryValue | QueryValue[]>;
  * const path = url`/users/${userId}/posts/${postId}`;
  */
 declare function url(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Immutable URL utility wrapper with convenience path/query operations.
+ */
 declare class URLPath {
   #private;
+  /**
+   * Creates a `URLPath` from a URL-like input and optional base URL.
+   *
+   * @param input URL value to parse.
+   * @param base Optional base URL for relative inputs.
+   */
   constructor(input: URLLike, base?: URLLike);
+  /**
+   * URL protocol including trailing `:`.
+   */
   get protocol(): string;
+  /**
+   * Host including port when present.
+   */
   get host(): string;
+  /**
+   * Hostname without port.
+   */
   get hostname(): string;
+  /**
+   * Port component, or an empty string when absent.
+   */
   get port(): string;
+  /**
+   * URL origin (`protocol + // + host`).
+   */
   get origin(): string;
+  /**
+   * Username component.
+   */
   get username(): string;
+  /**
+   * Password component.
+   */
   get password(): string;
+  /**
+   * Hash fragment including leading `#` when present.
+   */
   get hash(): string;
+  /**
+   * Search component including leading `?` when present.
+   */
   get search(): string;
+  /**
+   * Returns a copy of query parameters.
+   */
   get searchParams(): URLSearchParams;
+  /**
+   * URL pathname component.
+   */
   get pathname(): string;
+  /**
+   * Decoded pathname segments without empty parts.
+   */
   get parts(): string[];
+  /**
+   * Final path segment (decoded).
+   */
   get name(): string;
+  /**
+   * File suffix from {@link name}, including the leading dot.
+   */
   get suffix(): string;
+  /**
+   * File name without suffix from {@link name}.
+   */
   get stem(): string;
+  /**
+   * Parent path with the last path segment removed.
+   */
   get parent(): URLPath;
+  /**
+   * Appends path segments and returns a new URL.
+   *
+   * @param segments Segments to append.
+   */
   joinpath(...segments: string[]): URLPath;
+  /**
+   * Alias of {@link joinpath}.
+   *
+   * @param segments Segments to append.
+   */
   div(...segments: string[]): URLPath;
+  /**
+   * Creates a copy with replaced pathname parts.
+   *
+   * @param parts Decoded path parts.
+   */
   private withPath;
+  /**
+   * Replaces query parameter values for the provided keys.
+   *
+   * @param params Query values to set.
+   */
   withQuery(params: QueryObject): URLPath;
+  /**
+   * Alias of {@link withQuery}.
+   *
+   * @param params Query values to set.
+   */
   withQueryPatch(params: QueryObject): URLPath;
+  /**
+   * Appends query parameter values without deleting existing values.
+   *
+   * @param params Query values to append.
+   */
   appendQuery(params: QueryObject): URLPath;
+  /**
+   * Removes query keys whose values are entirely empty strings.
+   */
   withoutEmptyQuery(): URLPath;
+  /**
+   * Removes selected query keys.
+   *
+   * @param keys Query keys to remove.
+   */
   withoutQuery(...keys: string[]): URLPath;
+  /**
+   * Sets the hash fragment and returns a new URL.
+   *
+   * @param hash Hash value with or without leading `#`.
+   */
   withHash(hash: string): URLPath;
+  /**
+   * Removes the hash fragment.
+   */
   withoutHash(): URLPath;
+  /**
+   * Calls global `fetch` with this URL as input.
+   *
+   * @param init Optional fetch options.
+   */
   fetch(init?: RequestInit): Promise<Response>;
+  /**
+   * Resolves a relative URL against this URL.
+   *
+   * @param relative Relative URL/path.
+   */
   resolve(relative: string): URLPath;
+  /**
+   * Compares URLs by normalized string value.
+   *
+   * @param other URL to compare.
+   */
   equals(other: URLLike): boolean;
+  /**
+   * Returns a new native `URL` instance.
+   */
   toURL(): URL;
+  /**
+   * Returns the URL as a string.
+   */
   toString(): string;
+  /**
+   * Primitive value representation.
+   */
   valueOf(): string;
+  /**
+   * Primitive coercion hook.
+   */
   [Symbol.toPrimitive](): string;
+  /**
+   * Creates a `URLPath` from URL-like input.
+   *
+   * @param input URL value to parse.
+   * @param base Optional base URL for relative inputs.
+   */
   static from(input: URLLike, base?: URLLike): URLPath;
+  /**
+   * Parses an absolute URL string.
+   *
+   * @param input URL string to parse.
+   */
   static parse(input: string): URLPath;
+  private appendQueryValue;
 }
 //#endregion
 export { QueryObject, QueryValue, URLLike, URLPath, url };

package/dist/url.mjs

@@ -1 +1 @@
-function e(e,...t){let n=``;for(let r=0;r<e.length;r++)n+=e[r],r<t.length&&(n+=encodeURIComponent(String(t[r])));return n}function t(e,n,r){if(r!=null){if(Array.isArray(r)){for(let i of r)t(e,n,i);return}if(typeof r==`object`){try{e.append(n,JSON.stringify(r))}catch{e.append(n,String(r))}return}e.append(n,String(r))}}var n=class e{#e;constructor(t,n){t instanceof e||t instanceof URL?this.#e=new URL(t.toString()):n?this.#e=new URL(t,n.toString()):this.#e=new URL(t)}get protocol(){return this.#e.protocol}get host(){return this.#e.host}get hostname(){return this.#e.hostname}get port(){return this.#e.port}get origin(){return this.#e.origin}get username(){return this.#e.username}get password(){return this.#e.password}get hash(){return this.#e.hash}get search(){return this.#e.search}get searchParams(){return new URLSearchParams(this.#e.search)}get pathname(){return this.#e.pathname}get parts(){return this.#e.pathname.split(`/`).filter(Boolean).map(decodeURIComponent)}get name(){return this.parts.at(-1)??``}get suffix(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(t):``}get stem(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(0,t):e}get parent(){let e=this.parts.slice(0,-1);return this.withPath(e)}joinpath(...e){let t=[...this.parts,...e.map(e=>e.replace(/^\/+|\/+$/g,``))];return this.withPath(t)}div(...e){return this.joinpath(...e)}withPath(t){let n=new URL(this.#e.toString());return n.pathname=`/`+t.map(encodeURIComponent).join(`/`),new e(n)}withQuery(n){let r=new URL(this.#e.toString());for(let[e,i]of Object.entries(n))r.searchParams.delete(e),t(r.searchParams,e,i);return new e(r)}withQueryPatch(e){return this.withQuery(e)}appendQuery(n){let r=new URL(this.#e.toString());for(let[e,i]of Object.entries(n))t(r.searchParams,e,i);return new e(r)}withoutEmptyQuery(){let t=new URL(this.#e.toString()),n=new Set;for(let e of t.searchParams.keys())n.has(e)||(n.add(e),t.searchParams.getAll(e).every(e=>e===``)&&t.searchParams.delete(e));return new e(t)}withoutQuery(...t){let n=new URL(this.#e.toString());for(let e of t)n.searchParams.delete(e);return new e(n)}withHash(t){let n=new URL(this.#e.toString());return n.hash=t.startsWith(`#`)?t:`#${t}`,new e(n)}withoutHash(){let t=new URL(this.#e.toString());return t.hash=``,new e(t)}async fetch(e){return fetch(this.#e,e)}resolve(t){return new e(t,this)}equals(t){return this.toString()===new e(t).toString()}toURL(){return new URL(this.#e.toString())}toString(){return this.#e.toString()}valueOf(){return this.toString()}[Symbol.toPrimitive](){return this.toString()}static from(t,n){return new e(t,n)}static parse(t){return new e(t)}};export{n as URLPath,e as url};
+function e(e,...t){let n=``;for(let r=0;r<e.length;r++)n+=e[r],r<t.length&&(n+=encodeURIComponent(String(t[r])));return n}var t=class e{#e;constructor(t,n){t instanceof e||t instanceof URL?this.#e=new URL(t.toString()):n?this.#e=new URL(t,n.toString()):this.#e=new URL(t)}get protocol(){return this.#e.protocol}get host(){return this.#e.host}get hostname(){return this.#e.hostname}get port(){return this.#e.port}get origin(){return this.#e.origin}get username(){return this.#e.username}get password(){return this.#e.password}get hash(){return this.#e.hash}get search(){return this.#e.search}get searchParams(){return new URLSearchParams(this.#e.search)}get pathname(){return this.#e.pathname}get parts(){return this.#e.pathname.split(`/`).filter(Boolean).map(decodeURIComponent)}get name(){return this.parts.at(-1)??``}get suffix(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(t):``}get stem(){let e=this.name,t=e.lastIndexOf(`.`);return t>=0?e.slice(0,t):e}get parent(){let e=this.parts.slice(0,-1);return this.withPath(e)}joinpath(...e){let t=[...this.parts,...e.map(e=>e.replace(/^\/+|\/+$/g,``))];return this.withPath(t)}div(...e){return this.joinpath(...e)}withPath(t){let n=new URL(this.#e.toString());return n.pathname=`/`+t.map(encodeURIComponent).join(`/`),new e(n)}withQuery(t){let n=new URL(this.#e.toString());for(let[e,r]of Object.entries(t))n.searchParams.delete(e),this.appendQueryValue(n.searchParams,e,r);return new e(n)}withQueryPatch(e){return this.withQuery(e)}appendQuery(t){let n=new URL(this.#e.toString());for(let[e,r]of Object.entries(t))this.appendQueryValue(n.searchParams,e,r);return new e(n)}withoutEmptyQuery(){let t=new URL(this.#e.toString()),n=new Set;for(let e of t.searchParams.keys())n.has(e)||(n.add(e),t.searchParams.getAll(e).every(e=>e===``)&&t.searchParams.delete(e));return new e(t)}withoutQuery(...t){let n=new URL(this.#e.toString());for(let e of t)n.searchParams.delete(e);return new e(n)}withHash(t){let n=new URL(this.#e.toString());return n.hash=t.startsWith(`#`)?t:`#${t}`,new e(n)}withoutHash(){let t=new URL(this.#e.toString());return t.hash=``,new e(t)}async fetch(e){return fetch(this.#e,e)}resolve(t){return new e(t,this)}equals(t){return this.toString()===new e(t).toString()}toURL(){return new URL(this.#e.toString())}toString(){return this.#e.toString()}valueOf(){return this.toString()}[Symbol.toPrimitive](){return this.toString()}static from(t,n){return new e(t,n)}static parse(t){return new e(t)}appendQueryValue(e,t,n){if(n!=null){if(Array.isArray(n)){for(let r of n)this.appendQueryValue(e,t,r);return}if(typeof n==`object`){try{e.append(t,JSON.stringify(n))}catch{e.append(t,String(n))}return}e.append(t,String(n))}}};export{t as URLPath,e as url};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@depthbomb/common",
-	"version": "2.0.0",
+	"version": "2.2.0",
 	"description": "A set of common utilities for TypeScript/JavaScript",
 	"license": "MIT",
 	"engines": {