utilful 1.0.0 → 1.1.0

package/dist/emitter.d.ts

@@ -0,0 +1,72 @@
+interface EventsMap {
+    [event: string]: any;
+}
+interface DefaultEvents extends EventsMap {
+    [event: string]: (...args: any) => void;
+}
+interface Unsubscribe {
+    (): void;
+}
+interface Emitter<Events extends EventsMap = DefaultEvents> {
+    /**
+     * Calls each of the listeners registered for a given event.
+     *
+     * @example
+     * emitter.emit('tick', tickType, tickDuration)
+     *
+     * @param event The event name.
+     * @param args The arguments for listeners.
+     */
+    emit: <K extends keyof Events>(this: this, event: K, ...args: Parameters<Events[K]>) => void;
+    /**
+     * Event names in keys and arrays with listeners in values.
+     *
+     * @example
+     * emitter1.events = emitter2.events
+     * emitter2.events = { }
+     */
+    events: Partial<{
+        [E in keyof Events]: Events[E][];
+    }>;
+    /**
+     * Add a listener for a given event.
+     *
+     * @example
+     * const unbind = emitter.on('tick', (tickType, tickDuration) => {
+     *   count += 1
+     * })
+     *
+     * disable () {
+     *   unbind()
+     * }
+     *
+     * @param event The event name.
+     * @param cb The listener function.
+     * @returns Unbind listener from event.
+     */
+    on: <K extends keyof Events>(this: this, event: K, cb: Events[K]) => Unsubscribe;
+}
+/**
+ * Create event emitter.
+ *
+ * @example
+ * import { createEmitter } from 'nanoevents'
+ *
+ * class Ticker {
+ *   constructor() {
+ *     this.emitter = createEmitter()
+ *   }
+ *   on(...args) {
+ *     return this.emitter.on(...args)
+ *   }
+ *   tick() {
+ *     this.emitter.emit('tick')
+ *   }
+ * }
+ *
+ * @remarks Ported from `nanoevents`.
+ * @see https://github.com/ai/nanoevents
+ */
+declare function createEmitter<Events extends EventsMap = DefaultEvents>(): Emitter<Events>;
+
+export { type Emitter, createEmitter };

package/dist/emitter.mjs

@@ -0,0 +1,18 @@
+function createEmitter() {
+  return {
+    emit(event, ...args) {
+      for (let callbacks = this.events[event] || [], i = 0, length = callbacks.length; i < length; i++) {
+        callbacks[i](...args);
+      }
+    },
+    events: {},
+    on(event, cb) {
+      (this.events[event] ||= []).push(cb);
+      return () => {
+        this.events[event] = this.events[event]?.filter((i) => cb !== i);
+      };
+    }
+  };
+}
+
+export { createEmitter };

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+export { MaybeArray, toArray } from './array.mjs';
+export { CSVRow, createCSV, escapeCSVValue, parseCSV } from './csv.mjs';
+export { Emitter, createEmitter } from './emitter.mjs';
+export { cloneJSON, tryParseJSON } from './json.mjs';
+export { lazy } from './lazy.mjs';
+export { interopDefault } from './module.mjs';
+export { deepApply, objectEntries, objectKeys } from './object.mjs';
+export { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from './path.mjs';
+export { generateRandomId, template } from './string.mjs';
+export { AutocompletableString, LooseAutocomplete, UnifyIntersection } from './types.mjs';

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { MaybeArray, toArray } from './array.js';
+export { CSVRow, createCSV, escapeCSVValue, parseCSV } from './csv.js';
+export { Emitter, createEmitter } from './emitter.js';
+export { cloneJSON, tryParseJSON } from './json.js';
+export { lazy } from './lazy.js';
+export { interopDefault } from './module.js';
+export { deepApply, objectEntries, objectKeys } from './object.js';
+export { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from './path.js';
+export { generateRandomId, template } from './string.js';
+export { AutocompletableString, LooseAutocomplete, UnifyIntersection } from './types.js';

package/dist/index.mjs

@@ -0,0 +1,9 @@
+export { toArray } from './array.mjs';
+export { createCSV, escapeCSVValue, parseCSV } from './csv.mjs';
+export { createEmitter } from './emitter.mjs';
+export { cloneJSON, tryParseJSON } from './json.mjs';
+export { lazy } from './lazy.mjs';
+export { interopDefault } from './module.mjs';
+export { deepApply, objectEntries, objectKeys } from './object.mjs';
+export { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from './path.mjs';
+export { generateRandomId, template } from './string.mjs';

package/dist/json.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Type-safe wrapper around `JSON.stringify`.
+ *
+ * @remarks
+ * Falls back to the original value if the JSON serialization fails or the value is not a string.
+ */
+declare function tryParseJSON<T = unknown>(value: unknown): T;
+/**
+ * Clones the given JSON value.
+ *
+ * @remarks
+ * The value must not contain circular references as JSON does not support them. It also must contain JSON serializable values.
+ */
+declare function cloneJSON<T>(value: T): T;
+
+export { cloneJSON, tryParseJSON };

package/dist/json.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type-safe wrapper around `JSON.stringify`.
+ *
+ * @remarks
+ * Falls back to the original value if the JSON serialization fails or the value is not a string.
+ */
+declare function tryParseJSON<T = unknown>(value: unknown): T;
+/**
+ * Clones the given JSON value.
+ *
+ * @remarks
+ * The value must not contain circular references as JSON does not support them. It also must contain JSON serializable values.
+ */
+declare function cloneJSON<T>(value: T): T;
+
+export { cloneJSON, tryParseJSON };

package/dist/json.mjs

@@ -0,0 +1,26 @@
+function tryParseJSON(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function cloneJSON(value) {
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((e) => typeof e !== "object" || e === null ? e : cloneJSON(e));
+  }
+  const result = {};
+  for (const k in value) {
+    const v = value[k];
+    result[k] = typeof v !== "object" || v === null ? v : cloneJSON(v);
+  }
+  return result;
+}
+
+export { cloneJSON, tryParseJSON };

package/dist/lazy.d.mts

@@ -0,0 +1,20 @@
+/**
+ * A simple general purpose memoizer utility.
+ * - Lazily computes a value when accessed
+ * - Auto-caches the result by overwriting the getter
+ * - Typesafe
+ *
+ * @remarks
+ * Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
+ *
+ * @example
+ * const myValue = lazy(() => 'Hello, World!')
+ * console.log(myValue.value) // Computes value, overwrites getter
+ * console.log(myValue.value) // Returns cached value
+ * console.log(myValue.value) // Returns cached value
+ */
+declare function lazy<T>(getter: () => T): {
+    value: T;
+};
+
+export { lazy };

package/dist/lazy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A simple general purpose memoizer utility.
+ * - Lazily computes a value when accessed
+ * - Auto-caches the result by overwriting the getter
+ * - Typesafe
+ *
+ * @remarks
+ * Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
+ *
+ * @example
+ * const myValue = lazy(() => 'Hello, World!')
+ * console.log(myValue.value) // Computes value, overwrites getter
+ * console.log(myValue.value) // Returns cached value
+ * console.log(myValue.value) // Returns cached value
+ */
+declare function lazy<T>(getter: () => T): {
+    value: T;
+};
+
+export { lazy };

package/dist/lazy.mjs

@@ -0,0 +1,11 @@
+function lazy(getter) {
+  return {
+    get value() {
+      const value = getter();
+      Object.defineProperty(this, "value", { value });
+      return value;
+    }
+  };
+}
+
+export { lazy };

package/dist/module.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Interop helper for default exports.
+ *
+ * @example
+ * const mod = await interopDefault(import('./module.js'))
+ */
+declare function interopDefault<T>(m: T | Promise<T>): Promise<T extends {
+    default: infer U;
+} ? U : T>;
+
+export { interopDefault };

package/dist/module.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Interop helper for default exports.
+ *
+ * @example
+ * const mod = await interopDefault(import('./module.js'))
+ */
+declare function interopDefault<T>(m: T | Promise<T>): Promise<T extends {
+    default: infer U;
+} ? U : T>;
+
+export { interopDefault };

package/dist/module.mjs

@@ -0,0 +1,6 @@
+async function interopDefault(m) {
+  const resolved = await m;
+  return resolved.default || resolved;
+}
+
+export { interopDefault };

package/dist/object.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Strictly typed `Object.keys`.
+ */
+declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${keyof T & (string | number | boolean | null | undefined)}`>;
+/**
+ * Strictly typed `Object.entries`.
+ */
+declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof T, T[keyof T]]>;
+/**
+ * Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays.
+ */
+declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void;
+
+export { deepApply, objectEntries, objectKeys };

package/dist/object.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Strictly typed `Object.keys`.
+ */
+declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${keyof T & (string | number | boolean | null | undefined)}`>;
+/**
+ * Strictly typed `Object.entries`.
+ */
+declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof T, T[keyof T]]>;
+/**
+ * Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays.
+ */
+declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void;
+
+export { deepApply, objectEntries, objectKeys };

package/dist/object.mjs

@@ -0,0 +1,25 @@
+function objectKeys(obj) {
+  return Object.keys(obj);
+}
+function objectEntries(obj) {
+  return Object.entries(obj);
+}
+function deepApply(data, callback) {
+  for (const [key, value] of Object.entries(data)) {
+    callback(data, key, value);
+    if (Array.isArray(value)) {
+      for (const element of value) {
+        if (isObject(element)) {
+          deepApply(element, callback);
+        }
+      }
+    } else if (isObject(value)) {
+      deepApply(value, callback);
+    }
+  }
+}
+function isObject(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+
+export { deepApply, objectEntries, objectKeys };

package/dist/path.d.mts

@@ -0,0 +1,40 @@
+type QueryValue = string | number | boolean | QueryValue[] | Record<string, any> | null | undefined;
+type QueryObject = Record<string, QueryValue | QueryValue[]>;
+/**
+ * Removes the leading slash from the given path if it has one.
+ */
+declare function withoutLeadingSlash(path?: string): string;
+/**
+ * Adds a leading slash to the given path if it does not already have one.
+ */
+declare function withLeadingSlash(path?: string): string;
+/**
+ * Removes the trailing slash from the given path if it has one.
+ */
+declare function withoutTrailingSlash(path?: string): string;
+/**
+ * Adds a trailing slash to the given path if it does not already have one
+ */
+declare function withTrailingSlash(path?: string): string;
+/**
+ * Joins the given URL path segments, ensuring that there is only one slash between them.
+ */
+declare function joinURL(...paths: (string | undefined)[]): string;
+/**
+ * Adds the base path to the input path, if it is not already present.
+ */
+declare function withBase(input?: string, base?: string): string;
+/**
+ * Removes the base path from the input path, if it is present.
+ */
+declare function withoutBase(input?: string, base?: string): string;
+/**
+ * Returns the pathname of the given path, which is the path without the query string.
+ */
+declare function getPathname(path?: string): string;
+/**
+ * Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
+ */
+declare function withQuery(input: string, query?: QueryObject): string;
+
+export { type QueryObject, type QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/path.d.ts

@@ -0,0 +1,40 @@
+type QueryValue = string | number | boolean | QueryValue[] | Record<string, any> | null | undefined;
+type QueryObject = Record<string, QueryValue | QueryValue[]>;
+/**
+ * Removes the leading slash from the given path if it has one.
+ */
+declare function withoutLeadingSlash(path?: string): string;
+/**
+ * Adds a leading slash to the given path if it does not already have one.
+ */
+declare function withLeadingSlash(path?: string): string;
+/**
+ * Removes the trailing slash from the given path if it has one.
+ */
+declare function withoutTrailingSlash(path?: string): string;
+/**
+ * Adds a trailing slash to the given path if it does not already have one
+ */
+declare function withTrailingSlash(path?: string): string;
+/**
+ * Joins the given URL path segments, ensuring that there is only one slash between them.
+ */
+declare function joinURL(...paths: (string | undefined)[]): string;
+/**
+ * Adds the base path to the input path, if it is not already present.
+ */
+declare function withBase(input?: string, base?: string): string;
+/**
+ * Removes the base path from the input path, if it is present.
+ */
+declare function withoutBase(input?: string, base?: string): string;
+/**
+ * Returns the pathname of the given path, which is the path without the query string.
+ */
+declare function getPathname(path?: string): string;
+/**
+ * Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
+ */
+declare function withQuery(input: string, query?: QueryObject): string;
+
+export { type QueryObject, type QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/path.mjs

@@ -0,0 +1,113 @@
+function withoutLeadingSlash(path) {
+  if (!path || path === "/") {
+    return "/";
+  }
+  return path[0] === "/" ? path.slice(1) : path;
+}
+function withLeadingSlash(path) {
+  if (!path || path === "/") {
+    return "/";
+  }
+  return path[0] === "/" ? path : `/${path}`;
+}
+function withoutTrailingSlash(path) {
+  if (!path || path === "/") {
+    return "/";
+  }
+  return path[path.length - 1] === "/" ? path.slice(0, -1) : path;
+}
+function withTrailingSlash(path) {
+  if (!path || path === "/") {
+    return "/";
+  }
+  return path[path.length - 1] === "/" ? path : `${path}/`;
+}
+function joinURL(...paths) {
+  let result = "";
+  for (let i = 0; i < paths.length; i++) {
+    const path = paths[i];
+    if (!result || result === "/") {
+      result = path || "/";
+      continue;
+    }
+    if (!path || path === "/") {
+      continue;
+    }
+    const resultHasTrailing = result[result.length - 1] === "/";
+    const pathHasLeading = path[0] === "/";
+    if (resultHasTrailing && pathHasLeading) {
+      result += path.slice(1);
+    } else if (!resultHasTrailing && !pathHasLeading) {
+      result += `/${path}`;
+    } else {
+      result += path;
+    }
+  }
+  return result;
+}
+function withBase(input = "", base = "") {
+  if (!base || base === "/") {
+    return input;
+  }
+  const _base = withoutTrailingSlash(base);
+  if (input.startsWith(_base)) {
+    return input;
+  }
+  return joinURL(_base, input);
+}
+function withoutBase(input = "", base = "") {
+  if (!base || base === "/") {
+    return input;
+  }
+  const _base = withoutTrailingSlash(base);
+  if (!input.startsWith(_base)) {
+    return input;
+  }
+  const trimmed = input.slice(_base.length);
+  return trimmed[0] === "/" ? trimmed : `/${trimmed}`;
+}
+function getPathname(path = "/") {
+  return path.startsWith("/") ? path.split("?")[0] : new URL(path, "http://localhost").pathname;
+}
+function withQuery(input, query) {
+  if (!query || Object.keys(query).length === 0) {
+    return input;
+  }
+  const searchIndex = input.indexOf("?");
+  const hasExistingParams = searchIndex !== -1;
+  const base = hasExistingParams ? input.slice(0, searchIndex) : input;
+  const searchParams = hasExistingParams ? new URLSearchParams(input.slice(searchIndex + 1)) : new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0) {
+      searchParams.delete(key);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0)
+        continue;
+      for (const item of value) {
+        if (item !== void 0) {
+          searchParams.append(key, normalizeQueryValue(item));
+        }
+      }
+    } else {
+      searchParams.set(key, normalizeQueryValue(value));
+    }
+  }
+  const queryString = searchParams.toString();
+  return queryString ? `${base}?${queryString}` : base;
+}
+function normalizeQueryValue(value) {
+  if (value === null) {
+    return "";
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+export { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/string.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Simple template engine to replace variables in a string.
+ *
+ * @example
+ * const str = 'Hello, {name}!'
+ * const variables = { name: 'world' }
+ *
+ * console.log(template(str, variables)) // Hello, world!
+ */
+declare function template(str: string, variables: Record<string | number, any>, fallback?: string | ((key: string) => string)): string;
+/**
+ * Generates a random string.
+ *
+ * @remarks Ported from `nanoid`.
+ * @see https://github.com/ai/nanoid
+ */
+declare function generateRandomId(size?: number, dict?: string): string;
+
+export { generateRandomId, template };

package/dist/string.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Simple template engine to replace variables in a string.
+ *
+ * @example
+ * const str = 'Hello, {name}!'
+ * const variables = { name: 'world' }
+ *
+ * console.log(template(str, variables)) // Hello, world!
+ */
+declare function template(str: string, variables: Record<string | number, any>, fallback?: string | ((key: string) => string)): string;
+/**
+ * Generates a random string.
+ *
+ * @remarks Ported from `nanoid`.
+ * @see https://github.com/ai/nanoid
+ */
+declare function generateRandomId(size?: number, dict?: string): string;
+
+export { generateRandomId, template };

package/dist/string.mjs

@@ -0,0 +1,16 @@
+const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+function template(str, variables, fallback) {
+  return str.replace(/\{(\w+)\}/g, (_, key) => {
+    return variables[key] || ((typeof fallback === "function" ? fallback(key) : fallback) ?? key);
+  });
+}
+function generateRandomId(size = 16, dict = URL_ALPHABET) {
+  let id = "";
+  let i = size;
+  const len = dict.length;
+  while (i--)
+    id += dict[Math.random() * len | 0];
+  return id;
+}
+
+export { generateRandomId, template };

package/dist/types.d.mts

@@ -0,0 +1,8 @@
+type AutocompletableString = string & {};
+type LooseAutocomplete<T extends string> = T | AutocompletableString;
+/** Also commonly referred to as `Prettify` */
+type UnifyIntersection<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+export type { AutocompletableString, LooseAutocomplete, UnifyIntersection };

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+type AutocompletableString = string & {};
+type LooseAutocomplete<T extends string> = T | AutocompletableString;
+/** Also commonly referred to as `Prettify` */
+type UnifyIntersection<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+export type { AutocompletableString, LooseAutocomplete, UnifyIntersection };

package/dist/types.mjs

@@ -0,0 +1 @@
+