@limitlesspc/std 0.20.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 limitlesspc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+<h1 align="center">std.js</h1>
+<p align="center">A standard library for JavaScript</p>

package/dist/array.d.ts

@@ -0,0 +1,209 @@
+import { Compare } from './cmp.js';
+import { Indexable, MaybeArray } from './types.js';
+
+/**
+ * @module
+ * Functions for working with arrays
+ */
+
+/**
+ * Switches the positions of two values in an array in-place
+ * @param array
+ * @param i the first index
+ * @param j the second index
+ * @example
+ * ```ts
+ * const array = [1, 2, 3, 4, 5];
+ * swap(array, 0, 4);
+ * console.log(array); // [5, 2, 3, 4, 1]
+ * ```
+ */
+declare function swap<T>(array: Indexable<T>, i: number, j: number): void;
+/**
+ * Removes a value from an array
+ * @param array
+ * @param item
+ * @returns if the item was removed
+ * @example
+ * ```ts
+ * const array = [1, 2, 3, 4, 5];
+ * console.log(remove(array, 3)); // true
+ * console.log(array); // [1, 2, 4, 5]
+ * console.log(remove(array, 3)); // false
+ * console.log(array); // [1, 2, 4, 5]
+ * ```
+ */
+declare function remove<T>(array: T[], item: T): boolean;
+/**
+ * Removes an item from an array without maintaining order
+ * @param array
+ * @param index
+ * @returns the removed item
+ * @example
+ * ```ts
+ * const array = [1, 2, 3, 4, 5];
+ * console.log(unorderedRemove(array, 1)); // 2
+ * console.log(array); // [1, 5, 3, 4]
+ * console.log(unorderedRemove(array, 1)); // 5
+ * console.log(array); // [1, 4, 3]
+ * ```
+ */
+declare function unorderedRemove<T>(array: T[], index: number): T | undefined;
+/**
+ * Returns an array containing items found in all arrays
+ * @param arrays
+ * @example
+ * ```ts
+ * console.log(intersection([1, 2, 3], [2, 3, 4], [3, 4, 5])); // [3]
+ * console.log(intersection([1, 2, 3], [4, 5, 6])); // []
+ * ```
+ */
+declare function intersection<T>(...arrays: ReadonlyArray<readonly T[]>): T[];
+/**
+ * Returns an array containing items found in the second array that are not in the first
+ * @param oldArray
+ * @param newArray
+ * @example
+ * ```ts
+ * console.log(added([1, 2, 3], [2, 3, 4])); // [4]
+ * console.log(added([1, 2, 3], [4, 5, 6])); // [4, 5, 6]
+ * ```
+ */
+declare function added<T, U>(oldArray: readonly T[], newArray: readonly U[]): U[];
+/**
+ * Returns an array containing items found in the first array that are not in the second
+ * @param oldArray
+ * @param newArray
+ * @example
+ * ```ts
+ * console.log(removed([1, 2, 3], [2, 3, 4])); // [1]
+ * console.log(removed([1, 2, 3], [4, 5, 6])); // [1, 2, 3]
+ * ```
+ */
+declare function removed<T, U>(oldArray: readonly T[], newArray: readonly U[]): T[];
+/**
+ * Get items that were added and removed from an array
+ * @param oldArray
+ * @param newArray
+ * @returns a tuple containing 1. the added items and 2. the removed items
+ * @example
+ * ```ts
+ * console.log(changes([1, 2, 3], [2, 3, 4])); // [[4], [1]]
+ * console.log(changes([1, 2, 3], [4, 5, 6])); // [[4, 5, 6], [1, 2, 3]]
+ * ```
+ */
+declare function changes<T, U>(oldArray: readonly T[], newArray: readonly U[]): [added: U[], removed: T[]];
+/**
+ * Determines if there is an item in one array that is not in the other
+ * @example
+ * ```ts
+ * console.log(hasChange([1, 2, 3], [1, 2, 3])); // false
+ * console.log(hasChange([1, 2, 3], [2, 3, 1])); // false
+ * console.log(hasChange([1, 2, 3], [1, 2, 6])); // true
+ * ```
+ */
+declare function hasChange(a: readonly any[], b: readonly any[]): boolean;
+/**
+ * Returns an array containing items found in either array, but not both
+ * @param array1
+ * @param array2
+ * @example
+ * ```ts
+ * console.log(difference([1, 2, 3], [2, 3, 4])); // [1, 4]
+ * console.log(difference([1, 2, 3], [4, 5, 6])); // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+declare function difference<T>(array1: readonly T[], array2: readonly T[]): T[];
+/**
+ * Returns an array containing items from all arrays deduplicated
+ * @param arrays
+ * @example
+ * ```ts
+ * console.log(union([1, 2, 3], [2, 3, 4], [3, 4, 5])); // [1, 2, 3, 4, 5]
+ * console.log(union([1, 2, 3], [4, 5, 6])); // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+declare function union<T>(...arrays: Array<Iterable<T>>): T[];
+/**
+ * Test if two arrays contain the same items in the same order
+ * @param a
+ * @param b
+ * @returns if the arrays are equal
+ * @example
+ * ```ts
+ * console.log(equal([1, 2, 3], [1, 2, 3])); // true
+ * console.log(equal([1, 2, 3], [3, 2, 1])); // false
+ * ```
+ */
+declare function equal<T>(a: readonly T[], b: readonly T[]): boolean;
+/**
+ * Check if an array contains at least one of the items in another
+ * @param a the array to check
+ * @param b items the array should include
+ * @returns if the `a` has at least one of the items in `b`
+ * @example
+ * ```ts
+ * console.log(includesAny([1, 2, 3], [2, 3, 4])); // true
+ * console.log(includesAny([1, 2, 3], [4, 5, 6])); // false
+ * ```
+ */
+declare function includesAny<T, U>(a: readonly T[], b: readonly U[]): boolean;
+/**
+ * Check if an array contains all of the items in another
+ * @param a the array to check
+ * @param b items the array should include
+ * @returns if the `a` has all of the items in `b`
+ * @example
+ * ```ts
+ * console.log(includesAll([1, 2, 3], [2, 3, 1])); // true
+ * console.log(includesAll([1, 2, 3], [4, 5, 6])); // false
+ * ```
+ */
+declare function includesAll<T, U>(a: readonly T[], b: readonly U[]): boolean;
+/**
+ * Returns a new array with items with a unique key
+ * @param array
+ * @param key
+ * @example
+ * ```ts
+ * const array = [
+ *   { id: 1, name: "Alice" },
+ *   { id: 2, name: "Bob" },
+ *   { id: 1, name: "Charlie" },
+ *   { id: 3, name: "David" },
+ *   { id: 2, name: "Eve" },
+ *   { id: 4, name: "Frank" },
+ * ];
+ * console.log(dedupe(array, "id")); // [
+ * // { id: 1, name: "Alice" },
+ * // { id: 2, name: "Bob" },
+ * // { id: 3, name: "David" },
+ * // { id: 4, name: "Frank" }
+ * // ]
+ */
+declare function dedupe<T extends {
+    [K in keyof T]: T[K];
+}>(array: Iterable<T>, key: keyof T): T[];
+declare function filterByKey<T>(array: readonly T[], key: keyof T): T[];
+/**
+ * Sorts an array of objects by the value of a key
+ * @param array
+ * @param key
+ * @param compare
+ * @example
+ * ```ts
+ * const array = [
+ *   { id: 3, name: "Charlie" },
+ *   { id: 1, name: "Alice" },
+ *   { id: 2, name: "Bob" },
+ * ];
+ * console.log(sortByKeys(array, "id")); // [
+ * // { id: 1, name: "Alice" },
+ * // { id: 2, name: "Bob" },
+ * // { id: 3, name: "Charlie" }
+ * // ]
+ * ```
+ */
+declare function sortByKeys<T, K extends keyof T>(array: Iterable<T>, key: MaybeArray<K>, compare?: Compare<T[K]>): T[];
+
+export { added, changes, dedupe, difference, equal, filterByKey, hasChange, includesAll, includesAny, intersection, remove, removed, sortByKeys, swap, union, unorderedRemove };

package/dist/array.js

@@ -0,0 +1,41 @@
+import {
+  added,
+  changes,
+  dedupe,
+  difference,
+  equal,
+  filterByKey,
+  hasChange,
+  includesAll,
+  includesAny,
+  intersection,
+  remove,
+  removed,
+  sortByKeys,
+  swap,
+  union,
+  unorderedRemove
+} from "./chunk-ILLWUQPY.js";
+import "./chunk-WBSY6KRH.js";
+import "./chunk-MG5VQSTV.js";
+import "./chunk-6F4PWJZI.js";
+import "./chunk-TMLWLR46.js";
+import "./chunk-LJSF3QBT.js";
+export {
+  added,
+  changes,
+  dedupe,
+  difference,
+  equal,
+  filterByKey,
+  hasChange,
+  includesAll,
+  includesAny,
+  intersection,
+  remove,
+  removed,
+  sortByKeys,
+  swap,
+  union,
+  unorderedRemove
+};

package/dist/async/index.d.ts

@@ -0,0 +1,48 @@
+import { uint, Awaitable, AnyFunction, Result } from '../types.js';
+
+type Task<T> = () => Awaitable<T>;
+interface TaskQueueItem<T> {
+    task: () => Awaitable<T>;
+    resolve: (result: T) => void;
+    reject: (reason?: any) => void;
+}
+declare class TaskQueue<T> {
+    protected tasks: Array<TaskQueueItem<T>>;
+    private stopped;
+    private paused;
+    private pendingTask;
+    constructor(tasks?: Array<TaskQueueItem<T>>);
+    get size(): uint;
+    enqueue(task: Task<T>, autoDequeue?: boolean): Promise<T>;
+    dequeue(): Promise<boolean>;
+    stop(): void;
+    pause(): void;
+    start(): Promise<boolean>;
+}
+
+/**
+ * @module
+ * Functions for working with promises
+ */
+
+declare const sleep: (ms?: number) => Promise<void>;
+declare function throttle<T extends AnyFunction>(func: T, ms: number): (...args: Parameters<T>) => void;
+declare function debounce<T extends AnyFunction>(func: T, ms: number): (...args: Parameters<T>) => void;
+/**
+ * Runs promises concurrently with a limit to the number of promises running at once
+ * @param funcs an iterable of functions that return promises
+ * @param max the most promises that can run at once
+ * @returns an array of results of all the promises in the order they were passed in
+ */
+declare function concurrently<T>(funcs: Iterable<() => Promise<T>>, max: number): Promise<T[]>;
+declare function retry<T>(fn: () => Promise<T>, { maxAttempts, delay }?: {
+    maxAttempts?: uint;
+    delay?: number;
+}): Promise<Result<T, unknown>>;
+declare function retryWithExponentialBackoff<T>(fn: () => Promise<T>, { maxAttempts, startDelay, multiplier, }?: {
+    maxAttempts?: uint;
+    startDelay?: number;
+    multiplier?: number;
+}): Promise<Result<T, unknown>>;
+
+export { TaskQueue, concurrently, debounce, retry, retryWithExponentialBackoff, sleep, throttle };

package/dist/async/index.js

@@ -0,0 +1,155 @@
+import {
+  Queue
+} from "../chunk-DO4NH5XG.js";
+import "../chunk-ILLWUQPY.js";
+import "../chunk-WBSY6KRH.js";
+import "../chunk-MG5VQSTV.js";
+import "../chunk-6F4PWJZI.js";
+import "../chunk-TMLWLR46.js";
+import "../chunk-LJSF3QBT.js";
+
+// src/async/queue.ts
+var TaskQueue = class {
+  constructor(tasks = []) {
+    this.tasks = tasks;
+  }
+  stopped = false;
+  paused = false;
+  pendingTask = false;
+  get size() {
+    return this.tasks.length;
+  }
+  async enqueue(task, autoDequeue = true) {
+    return new Promise((resolve, reject) => {
+      this.tasks.push({ task, resolve, reject });
+      if (autoDequeue) {
+        void this.dequeue();
+      }
+    });
+  }
+  async dequeue() {
+    if (this.pendingTask || this.paused) {
+      return false;
+    }
+    if (this.stopped) {
+      this.tasks.length = 0;
+      this.stopped = false;
+      return false;
+    }
+    const item = this.tasks.pop();
+    if (!item) {
+      return false;
+    }
+    try {
+      this.pendingTask = true;
+      const result = await item.task();
+      this.pendingTask = false;
+      item.resolve(result);
+    } catch (error) {
+      item.reject(error);
+      this.pendingTask = false;
+    }
+    void this.dequeue();
+    return true;
+  }
+  stop() {
+    this.stopped = true;
+  }
+  pause() {
+    this.paused = true;
+  }
+  async start() {
+    this.stopped = false;
+    this.paused = false;
+    return this.dequeue();
+  }
+};
+
+// src/async/index.ts
+var sleep = async (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms));
+function throttle(func, ms) {
+  let timeout;
+  let lastCalled = 0;
+  return (...args) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(
+      () => {
+        func(...args);
+        timeout = void 0;
+        lastCalled = Date.now();
+      },
+      ms - (Date.now() - lastCalled)
+    );
+  };
+}
+function debounce(func, ms) {
+  let timeout;
+  return (...args) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      func(...args);
+      timeout = void 0;
+    }, ms);
+  };
+}
+async function concurrently(funcs, max) {
+  const tasks = [...funcs];
+  const results = Array.from({ length: tasks.length });
+  const queue = new Queue(tasks);
+  const length = queue.size;
+  let i = 0;
+  return new Promise((resolve) => {
+    const next = async () => {
+      const func = queue.dequeue();
+      if (func) {
+        results[i++] = await func();
+        void next();
+      } else if (results.length === length) {
+        resolve(results);
+      }
+    };
+    for (let i2 = 0; i2 < max; i2++) {
+      void next();
+    }
+  });
+}
+async function retry(fn, { maxAttempts = 5, delay = 0 } = {}) {
+  let attempts = 0;
+  while (true) {
+    try {
+      return [await fn(), void 0];
+    } catch (error) {
+      if (++attempts >= maxAttempts) {
+        return [void 0, error];
+      }
+      await sleep(delay);
+    }
+  }
+}
+async function retryWithExponentialBackoff(fn, {
+  maxAttempts = 5,
+  startDelay = 1e3,
+  multiplier = 2
+} = {}) {
+  let attempts = 0;
+  while (true) {
+    try {
+      return [await fn(), void 0];
+    } catch (error) {
+      const delay = startDelay * multiplier ** attempts;
+      if (++attempts >= maxAttempts) {
+        return [void 0, error];
+      }
+      await sleep(delay);
+    }
+  }
+}
+export {
+  TaskQueue,
+  concurrently,
+  debounce,
+  retry,
+  retryWithExponentialBackoff,
+  sleep,
+  throttle
+};

package/dist/bytes.d.ts

@@ -0,0 +1,38 @@
+import { uint } from './types.js';
+
+/**
+ * @module
+ * Utilities for working with binary data
+ */
+
+declare const KILOBYTE = 1000;
+declare const MEGABYTE: number;
+declare const GIGABYTE: number;
+declare const TERABYTE: number;
+declare const KIBIBYTE = 1024;
+declare const MEBIBYTE: number;
+declare const GIBIBYTE: number;
+declare const TEBIBYTE: number;
+/**
+ * Convert binary into its hex representation
+ * @param buffer
+ * @returns hex string
+ * @example
+ * ```ts
+ * const buffer = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+ * console.log(hex(buffer)); // "48656c6c6f"
+ * ```
+ */
+declare function hex(buffer: Iterable<uint>): string;
+/**
+ * Convert a hex string into binary
+ * @param hex
+ * @returns uint8 buffer
+ * @example
+ * ```ts
+ * const buffer = unhex("48656c6c6f");
+ * console.log(buffer); // Uint8Array [ 72, 101, 108, 108, 111 ]
+ */
+declare function unhex(hex: string): Uint8Array;
+
+export { GIBIBYTE, GIGABYTE, KIBIBYTE, KILOBYTE, MEBIBYTE, MEGABYTE, TEBIBYTE, TERABYTE, hex, unhex };

package/dist/bytes.js

@@ -0,0 +1,35 @@
+// src/bytes.ts
+var KILOBYTE = 1e3;
+var MEGABYTE = 1e3 * KILOBYTE;
+var GIGABYTE = 1e3 * MEGABYTE;
+var TERABYTE = 1e3 * GIGABYTE;
+var KIBIBYTE = 1024;
+var MEBIBYTE = 1024 * KIBIBYTE;
+var GIBIBYTE = 1024 * MEBIBYTE;
+var TEBIBYTE = 1024 * GIBIBYTE;
+function hex(buffer) {
+  const hexCodes = [];
+  for (const element of buffer) {
+    hexCodes.push(element.toString(16).padStart(2, "0"));
+  }
+  return hexCodes.join("");
+}
+function unhex(hex2) {
+  const bytes = new Uint8Array(hex2.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex2.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+export {
+  GIBIBYTE,
+  GIGABYTE,
+  KIBIBYTE,
+  KILOBYTE,
+  MEBIBYTE,
+  MEGABYTE,
+  TEBIBYTE,
+  TERABYTE,
+  hex,
+  unhex
+};