utilful 1.2.1 → 2.1.0

package/dist/array.d.mts

@@ -1,10 +0,0 @@
-/**
- * Represents a value that can be either a single value or an array of values.
- */
-type MaybeArray<T> = T | T[];
-/**
- * Converts `MaybeArray<T>` to `Array<T>`.
- */
-declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[];
-
-export { type MaybeArray, toArray };

package/dist/array.mjs

@@ -1,6 +0,0 @@
-function toArray(array) {
-  array ??= [];
-  return Array.isArray(array) ? array : [array];
-}
-
-export { toArray };

package/dist/csv.d.mts

@@ -1,67 +0,0 @@
-/**
- * Represents a row in a CSV file with column names of type T.
- */
-type CSVRow<T extends string = string> = Record<T, string>;
-/**
- * Converts an array of objects to a comma-separated values (CSV) string
- * that contains only the `columns` specified.
- *
- * @example
- * const data = [
- *   { name: 'John', age: '30', city: 'New York' },
- *   { name: 'Jane', age: '25', city: 'Boston' }
- * ]
- *
- * const csv = createCSV(data, ['name', 'age'])
- * // name,age
- * // John,30
- * // Jane,25
- */
-declare function createCSV<T extends Record<string, unknown>>(data: T[], columns: (keyof T)[], options?: {
-    /** @default ',' */
-    delimiter?: string;
-    /** @default true */
-    addHeader?: boolean;
-    /** @default false */
-    quoteAll?: boolean;
-}): string;
-/**
- * Escapes a value for a CSV string.
- *
- * @remarks
- * Returns an empty string if the value is `null` or `undefined`.
- * Values containing delimiters, quotes, or line breaks are quoted.
- * Within quoted values, double quotes are escaped by doubling them.
- *
- * @example
- * escapeCSVValue('hello, world'); // "hello, world"
- * escapeCSVValue('contains "quotes"'); // "contains ""quotes"""
- */
-declare function escapeCSVValue(value: unknown, options?: {
-    /** @default ',' */
-    delimiter?: string;
-    /** @default false */
-    quoteAll?: boolean;
-}): string;
-/**
- * Parses a comma-separated values (CSV) string into an array of objects.
- *
- * @remarks
- * The first row of the CSV string is used as the header row.
- *
- * @example
- * const csv = `name,age
- * John,30
- * Jane,25`
- *
- * const data = parseCSV<'name' | 'age'>(csv)
- * // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
- */
-declare function parseCSV<Header extends string>(csv?: string | null | undefined, options?: {
-    /** @default ',' */
-    delimiter?: string;
-    /** @default true */
-    trimValues?: boolean;
-}): CSVRow<Header>[];
-
-export { type CSVRow, createCSV, escapeCSVValue, parseCSV };

package/dist/csv.mjs

@@ -1,77 +0,0 @@
-function createCSV(data, columns, options = {}) {
-  const {
-    delimiter = ",",
-    addHeader = true,
-    quoteAll = false
-  } = options;
-  const escapeAndQuote = (value) => escapeCSVValue(value, { delimiter, quoteAll });
-  const rows = data.map(
-    (obj) => columns.map((key) => escapeAndQuote(obj[key])).join(delimiter)
-  );
-  if (addHeader) {
-    rows.unshift(columns.map(escapeAndQuote).join(delimiter));
-  }
-  return rows.join("\n");
-}
-function escapeCSVValue(value, options = {}) {
-  const {
-    delimiter = ",",
-    quoteAll = false
-  } = options;
-  if (value == null) {
-    return "";
-  }
-  const stringValue = String(value);
-  const needsQuoting = quoteAll || stringValue.includes(delimiter) || stringValue.includes('"') || stringValue.includes("\n") || stringValue.includes("\r");
-  if (needsQuoting) {
-    return `"${stringValue.replaceAll('"', '""')}"`;
-  }
-  return stringValue;
-}
-function parseCSV(csv, options = {}) {
-  if (!csv?.trim())
-    return [];
-  const rows = [];
-  let currentRow = [];
-  let currentField = "";
-  let inQuotes = false;
-  const { delimiter = ",", trimValues = true } = options;
-  for (let i = 0; i < csv.length; i++) {
-    const char = csv[i];
-    const nextChar = i + 1 < csv.length ? csv[i + 1] : "";
-    if (char === '"') {
-      if (inQuotes && nextChar === '"') {
-        currentField += '"';
-        i++;
-      } else {
-        inQuotes = !inQuotes;
-      }
-    } else if (char === delimiter && !inQuotes) {
-      currentRow.push(trimValues ? currentField.trim() : currentField);
-      currentField = "";
-    } else if ((char === "\n" || char === "\r" && nextChar === "\n") && !inQuotes) {
-      if (char === "\r")
-        i++;
-      currentRow.push(trimValues ? currentField.trim() : currentField);
-      rows.push(currentRow);
-      currentRow = [];
-      currentField = "";
-    } else {
-      currentField += char;
-    }
-  }
-  if (currentField || currentRow.length > 0) {
-    currentRow.push(trimValues ? currentField.trim() : currentField);
-    rows.push(currentRow);
-  }
-  if (rows.length <= 1)
-    return [];
-  const headers = rows[0];
-  return rows.slice(1).filter((row) => row.some((field) => field.trim().length > 0)).map((values) => {
-    return Object.fromEntries(
-      headers.map((header, index) => [header, index < values.length ? values[index] : ""])
-    );
-  });
-}
-
-export { createCSV, escapeCSVValue, parseCSV };

package/dist/emitter.d.mts

@@ -1,24 +0,0 @@
-type EventType = string | symbol;
-type Handler<T = unknown> = (event: T) => void;
-type WildcardHandler<T = Record<string, unknown>> = (type: keyof T, event: T[keyof T]) => void;
-type EventHandlerList<T = unknown> = Handler<T>[];
-type WildCardEventHandlerList<T = Record<string, unknown>> = WildcardHandler<T>[];
-type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | '*', EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
-interface Emitter<Events extends Record<EventType, unknown>> {
-    events: EventHandlerMap<Events>;
-    on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
-    on(type: '*', handler: WildcardHandler<Events>): void;
-    off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): void;
-    off(type: '*', handler: WildcardHandler<Events>): void;
-    emit<Key extends keyof Events>(type: Key, event: Events[Key]): void;
-    emit<Key extends keyof Events>(type: undefined extends Events[Key] ? Key : never): void;
-}
-/**
- * Simple functional event emitter / pubsub.
- *
- * @remarks Ported from `mitt`.
- * @see https://github.com/developit/mitt
- */
-declare function createEmitter<Events extends Record<EventType, unknown>>(events?: EventHandlerMap<Events>): Emitter<Events>;
-
-export { type Emitter, type EventHandlerList, type EventHandlerMap, type EventType, type Handler, type WildCardEventHandlerList, type WildcardHandler, createEmitter };

package/dist/emitter.mjs

@@ -1,63 +0,0 @@
-function createEmitter(events) {
-  events ||= /* @__PURE__ */ new Map();
-  return {
-    /**
-     * A Map of event names to registered handler functions.
-     */
-    events,
-    /**
-     * Register an event handler for the given type.
-     *
-     * @memberOf createEmitter
-     */
-    on(type, handler) {
-      const handlers = events.get(type);
-      if (handlers) {
-        handlers.push(handler);
-      } else {
-        events.set(type, [handler]);
-      }
-    },
-    /**
-     * Remove an event handler for the given type.
-     *
-     * @remarks
-     * If `handler` is omitted, all handlers of the given type are removed.
-     *
-     * @memberOf createEmitter
-     */
-    off(type, handler) {
-      const handlers = events.get(type);
-      if (handlers) {
-        if (handler) {
-          handlers.splice(handlers.indexOf(handler) >>> 0, 1);
-        } else {
-          events.set(type, []);
-        }
-      }
-    },
-    /**
-     * Invoke all handlers for the given type.
-     *
-     * @remarks
-     * If present, `'*'` handlers are invoked after type-matched handlers.
-     * Manually firing '*' handlers is not supported.
-     *
-     * @memberOf createEmitter
-     */
-    emit(type, evt) {
-      let handlers = events.get(type);
-      if (handlers) {
-        for (const handler of [...handlers])
-          handler(evt);
-      }
-      handlers = events.get("*");
-      if (handlers) {
-        for (const handler of [...handlers])
-          handler(type, evt);
-      }
-    }
-  };
-}
-
-export { createEmitter };

package/dist/index.d.mts

@@ -1,10 +0,0 @@
-export { MaybeArray, toArray } from './array.mjs';
-export { CSVRow, createCSV, escapeCSVValue, parseCSV } from './csv.mjs';
-export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, 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.mjs

@@ -1,9 +0,0 @@
-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

@@ -1,16 +0,0 @@
-/**
- * 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

@@ -1,26 +0,0 @@
-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

@@ -1,20 +0,0 @@
-/**
- * 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

@@ -1,20 +0,0 @@
-/**
- * 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

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

package/dist/module.d.mts

@@ -1,11 +0,0 @@
-/**
- * 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

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

package/dist/object.d.mts

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,25 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,113 +0,0 @@
-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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1 +0,0 @@
-