@oviirup/utils 0.0.1-canary.0

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Avirup Ghosh
+
+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/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@oviirup/utils",
+  "version": "0.0.1-canary.0",
+  "description": "Collection of common JavaScript / TypeScript utilities bt @oviirup",
+  "repository": "oviirup/utils",
+  "license": "MIT",
+  "author": "Avirup Ghosh (oviirup)",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./array": {
+      "types": "./dist/array.d.ts",
+      "import": "./dist/array.mjs",
+      "require": "./dist/array.js"
+    },
+    "./assertions": {
+      "types": "./dist/assertions.d.ts",
+      "import": "./dist/assertions.mjs",
+      "require": "./dist/assertions.js"
+    },
+    "./nanoid": {
+      "types": "./dist/nanoid.d.ts",
+      "import": "./dist/nanoid.mjs",
+      "require": "./dist/nanoid.js"
+    },
+    "./number": {
+      "types": "./dist/number.d.ts",
+      "import": "./dist/number.mjs",
+      "require": "./dist/number.js"
+    },
+    "./object": {
+      "types": "./dist/object.d.ts",
+      "import": "./dist/object.mjs",
+      "require": "./dist/object.js"
+    },
+    "./string": {
+      "types": "./dist/string.d.ts",
+      "import": "./dist/string.mjs",
+      "require": "./dist/string.js"
+    }
+  },
+  "scripts": {
+    "build": "bunchee --minify --no-sourcemap",
+    "format": "biome format --write",
+    "lint": "biome lint",
+    "prepare": "husky",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2",
+    "@types/bun": "^1",
+    "@types/node": "^24",
+    "bunchee": "^6",
+    "husky": "^9",
+    "lint-staged": "^16",
+    "typescript": "^5",
+    "vitest": "^4"
+  },
+  "lint-staged": {
+    "*.{js,mjs,ts,json,md}": "biome format --write"
+  }
+}

package/readme.md

@@ -0,0 +1,7 @@
+# @oviirup/utils ![](https://img.shields.io/badge/WIP-gold)
+
+Collection of common JavaScript / TypeScript utilities by [@oviirup](https://github.com/oviirup).
+
+- Type-safe utilities for everyday coding
+- Zero dependencies
+- Thoroughly tested

package/src/array.ts

@@ -0,0 +1,122 @@
+import { isEmptyArray } from "./assertions";
+
+/**
+ * Converts a given value to represent itself in an array
+ * @param value The value to convert to an array
+ * @category Array
+ */
+export function toArray<T>(array: T | T[]): T[] {
+  array = array ?? [];
+  return Array.isArray(array) ? array : [array];
+}
+
+type Matcher<T> = (left: T, right: T) => boolean;
+
+/**
+ * Create an array with all unique items
+ * @param value The array to make unique
+ * @param equals The matcher function to use to determine if two items are the same
+ * @category Array
+ */
+export function unique<T>(value: T[]): T[];
+export function unique<T>(value: T[], equals: Matcher<T>): T[];
+export function unique<T>(value: T[], equals?: Matcher<T>): T[] {
+  if (typeof equals !== "function") {
+    return Array.from(new Set(value));
+  }
+  return value.reduce<T[]>((acc, item) => {
+    const index = acc.findIndex((e) => equals(e, item));
+    if (index === -1) acc.push(item);
+    return acc;
+  }, []);
+}
+
+/**
+ * Get nth item of Array. Negative for backward
+ * @param array The array to get the item from
+ * @param index The index of the item to get.
+ * @category Array
+ */
+export function at(array: readonly [], index: number): undefined;
+export function at<T>(array: readonly T[], index: number): T;
+export function at<T>(array: readonly T[] | [], index: number): T | undefined {
+  const len = array.length;
+  if (!len) return undefined;
+  if (index < 0) index += len;
+  return array[index];
+}
+
+/**
+ * Get last item
+ * @category Array
+ */
+export function last(array: readonly []): undefined;
+export function last<T>(array: readonly T[]): T;
+export function last<T>(array: readonly T[]): T | undefined {
+  return at(array, -1);
+}
+
+/**
+ * Get first item
+ * @category Array
+ */
+export function first(array: readonly []): undefined;
+export function first<T>(array: readonly T[]): T;
+export function first<T>(array: readonly T[]): T | undefined {
+  return at(array, 0);
+}
+
+/**
+ * Generate a range array of numbers.
+ * @category Array
+ */
+export function range(stop: number): number[];
+export function range(start: number, stop: number, step?: number): number[];
+export function range(...args: any): number[] {
+  let start = 0;
+  let stop: number;
+  let step = 1;
+  if (args.length === 1) {
+    [stop] = args;
+  } else {
+    [start, stop, step = 1] = args;
+  }
+  const array: number[] = [];
+  let current = start;
+  while (current < stop) {
+    array.push(current);
+    current += step;
+  }
+  return array;
+}
+
+type Predicate<T> = (item: T, index: number, array: T[]) => boolean;
+
+/**
+ * Filter an array in place (faster than Array.filter)
+ * @param array The array to filter
+ * @param predicate The predicate function to use to filter the array
+ * @category Array
+ */
+export function toFiltered<T>(array: T[], predicate: Predicate<T>): T[] {
+  for (let i = array.length; i--; i >= 0) {
+    if (!predicate(array[i], i, array)) array.splice(i, 1);
+  }
+  return array;
+}
+
+/**
+ * Move an item in an array to a new position
+ * @param array The array to move the item in
+ * @param from The index of the item to move
+ * @param to The index to move the item to
+ * @category Array
+ */
+export function move<T>(array: T[], from: number, to: number): T[] {
+  if (isEmptyArray(array)) return array;
+  if (from === to) return array;
+  const item = array[from];
+  array.splice(from, 1);
+  array.splice(to, 0, item);
+  return array;
+}

package/src/assertions.ts

@@ -0,0 +1,70 @@
+type Dict<T = unknown> = Record<string, T>;
+
+/** Check if given value is a string */
+export function isString(val: unknown): val is string {
+  return typeof val === "string";
+}
+
+/** Check if the given value is a number */
+export function isNumber(val: unknown): val is number {
+  return typeof val === "number" && !Number.isNaN(val);
+}
+
+/** Check if the given value is an integer */
+export function isInteger(val: unknown): val is number {
+  return isNumber(val) && Number.isInteger(val);
+}
+
+/** Check if the given value is a float */
+export function isFloat(val: unknown): val is number {
+  return isNumber(val) && !Number.isInteger(val);
+}
+
+/** Check if given value is an array */
+export function isArray<T = any>(value: unknown): value is T[] {
+  return Array.isArray(value);
+}
+
+/** Check if given array is empty */
+export function isEmptyArray(value: any[]): boolean {
+  return isArray(value) && value.length === 0;
+}
+
+/** Check if given value is an object */
+export function isObject<T extends object = Dict>(val: unknown): val is T {
+  return val !== null && typeof val === "object" && !Array.isArray(val);
+}
+
+/** Check if given object is empty */
+export function isEmptyObject<T extends object = Dict>(val: T): boolean {
+  return isObject(val) && Object.keys(val).length === 0;
+}
+
+/** Check if the given value is empty, null, undefined, or a string with no content */
+export function isEmpty(val: unknown): boolean {
+  if (val === null || val === undefined) return true;
+  if (typeof val === "string" && val.trim() === "") return true;
+  if (isArray(val)) return isEmptyArray(val);
+  if (isObject(val)) return isEmptyObject(val);
+  return false;
+}
+
+type Func<T> = (...args: any[]) => T;
+/** Check if the given object is a function */
+export function isFunction<T = unknown>(val: unknown): val is Func<T> {
+  return typeof val === "function";
+}
+
+/** Check if the given value is a regex */
+export function isRegex(value: unknown): value is RegExp {
+  return value instanceof RegExp;
+}
+
+/** Check if the given value is truthy */
+export function isTruthy(val: unknown): boolean {
+  return !!val;
+}
+
+export function isBrowser(): boolean {
+  return typeof window !== "undefined";
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./array";
+export * from "./assertions";
+export * from "./nanoid";
+export * from "./number";
+export * from "./object";
+export * from "./string";

package/src/nanoid.ts

@@ -0,0 +1,28 @@
+import { randomBytes } from "node:crypto";
+
+export const charset = `abcdefghijklmnopqrstuvwxyz_ABCDEFGHIJKLMNOPQRSTUVWXYZ-0123456789`;
+
+/**
+ * Generate a secure nanoid string using Node.js crypto module.
+ * @param length - Length of the ID (default: 21)
+ * @param alphabets - Alphabet to use for the ID
+ * @returns A cryptographically secure unique ID string
+ * @source https://github.com/ai/nanoid
+ */
+export function nanoid(length = 21, alphabets = charset): string {
+  const size = alphabets.length;
+  if (size === 0 || size > 255) {
+    throw new Error("Alphabet must contain less than 255 characters");
+  }
+  const mask = (2 << Math.floor(Math.log2(size - 1))) - 1;
+  const step = Math.ceil((1.6 * mask * length) / size);
+  let id = "";
+  while (id.length < length) {
+    const bytes = randomBytes(step);
+    for (let i = 0; i < step && id.length < length; i++) {
+      const index = bytes[i] & mask;
+      if (index < size) id += alphabets[index];
+    }
+  }
+  return id;
+}

package/src/number.ts

@@ -0,0 +1,59 @@
+import { isNumber, isObject } from "./assertions";
+
+/**
+ * Clamps a number between a minimum and maximum value
+ * @category Number
+ */
+export function clamp(val: number, min: number, max: number): number {
+  return Math.min(Math.max(val, min), max);
+}
+
+const baseAbbreviationSymbols = ["", "K", "M", "B", "T"];
+
+export type AbbreviationSymbols = Record<string, number> | string[];
+export type AbbreviateOptions = {
+  symbols?: AbbreviationSymbols;
+  precision?: number;
+};
+
+/**
+ * Abbreviates a number to a string with a symbol and a precision
+ * @param value - The number to abbreviate
+ * @param arg - The precision or options to use for the abbreviation
+ * @category Number
+ */
+export function abbreviate(value: number, precision?: number): string;
+export function abbreviate(value: number, options?: AbbreviateOptions): string;
+export function abbreviate(
+  value: number,
+  arg?: number | AbbreviateOptions | undefined,
+): string {
+  if (!isNumber(value)) return "0";
+  // parse arguments
+  let precision = 1;
+  let symbols: AbbreviationSymbols = baseAbbreviationSymbols;
+  if (typeof arg === "number") {
+    precision = arg;
+  } else if (typeof arg === "object") {
+    precision = arg.precision ?? 1;
+    symbols = arg.symbols ?? baseAbbreviationSymbols;
+  }
+  // get threshold symbols as tuples
+  const thresholds: [string, number][] = isObject(symbols)
+    ? Object.entries(symbols)
+    : symbols.map((symbol, i) => [symbol, 10 ** (i * 3)]);
+  // sort thresholds from largest to smallest
+  thresholds.sort((a, b) => b[1] - a[1]);
+  // handle negative values
+  const sign = value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+  // find the appropriate symbol
+  for (const [symbol, threshold] of thresholds) {
+    const frac = (abs / threshold).toFixed(precision);
+    if (Number(frac) < 1) continue;
+    return `${sign}${frac}${symbol}`;
+  }
+  // if the number is an integer, return it as is
+  if (Math.floor(abs) === abs) return value.toString();
+  return `${sign}${abs.toFixed(precision)}`;
+}

package/src/object.ts

@@ -0,0 +1,45 @@
+import { toArray } from "./array";
+import { isObject } from "./assertions";
+
+type Dict<T = unknown> = Record<string, T>;
+
+/**
+ * Checks if a given object has a specified key
+ * @category Object
+ */
+export function keyInObject<T extends object = Dict>(
+  val: T,
+  key: keyof T | (string & {}),
+): boolean {
+  return isObject(val) && key in val;
+}
+
+/**
+ * Picks a set of keys from an object
+ * @category Object
+ */
+export function pick<T extends object, K extends keyof T = keyof T>(
+  input: T,
+  keys: K | K[],
+): Pick<T, K> {
+  const picked = {} as Pick<T, K>;
+  for (const key of toArray(keys)) {
+    if (key in input) picked[key] = input[key];
+  }
+  return picked;
+}
+
+/**
+ * Omits a set of keys from an object
+ * @category Object
+ */
+export function omit<T extends object, K extends keyof T = keyof T>(
+  input: T,
+  keys: K | K[],
+): Omit<T, K> {
+  const partial = { ...input } as T;
+  for (const key of toArray(keys)) {
+    if (key in input) delete partial[key];
+  }
+  return partial as Omit<T, K>;
+}

package/src/string.ts

@@ -0,0 +1,34 @@
+/**
+ * Replace backslash to slash
+ * @category String
+ */
+export function slash(str: string) {
+  return str.replace(/\\/g, "/");
+}
+
+const DEFAULT_TRUNCATE_LENGTH = 80;
+/**
+ * Truncates a string to the specified length, adding "..." if it was longer.
+ * @param text The string to truncate
+ * @param length Maximum allowed length before truncation
+ * @category String
+ */
+export function truncate(
+  input: string,
+  length = DEFAULT_TRUNCATE_LENGTH,
+): string {
+  if (!input) return input;
+  const text = input.trim();
+  const maxLength = Math.max(3, length);
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3)}...`;
+}
+
+/**
+ * Capitalizes the first letter of a string
+ * @param input The string to capitalize
+ * @category String
+ */
+export function capitalize(input: string): string {
+  return input.charAt(0).toUpperCase() + input.slice(1);
+}

package/tests/array.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it, test } from "vitest";
+import * as array from "../src/array";
+
+describe("toArray", () => {
+  it.each([
+    { input: 1, expected: [1] },
+    { input: [1, 2, 3], expected: [1, 2, 3] },
+    { input: null, expected: [] },
+    { input: undefined, expected: [] },
+    { input: "foo", expected: ["foo"] },
+    { input: ["foo"], expected: ["foo"] },
+  ])("should convert $input to $expected", ({ input, expected }) => {
+    expect(array.toArray(input)).toEqual(expected);
+  });
+});
+
+test("range", () => {
+  expect(array.range(0)).toEqual([]);
+  expect(array.range(5)).toEqual([0, 1, 2, 3, 4]);
+  expect(array.range(2, 5)).toEqual([2, 3, 4]);
+  expect(array.range(2, 10, 2)).toEqual([2, 4, 6, 8]);
+});

package/tests/nanoid.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { charset, nanoid } from "../src/nanoid";
+
+describe("nanoid", () => {
+  it("should be ready for 0 size", () => {
+    expect(nanoid(0)).toBe("");
+  });
+
+  it("should generates URL-friendly IDs", () => {
+    const charset = `abcdefghijklmnopqrstuvwxyz_ABCDEFGHIJKLMNOPQRSTUVWXYZ-0123456789`;
+    for (let i = 0; i < 100; i++) {
+      const id = nanoid();
+      expect(id.length).toBe(21);
+      expect(typeof id).toBe("string");
+      for (const char of id) expect(charset.includes(char)).toBe(true);
+    }
+  });
+
+  it("should generate IDs with with given length", () => {
+    expect(nanoid(10).length).toBe(10);
+  });
+
+  it("should not have any collisions", () => {
+    const ids = new Set<string>();
+    const iterations = 100_000;
+    for (let i = 0; i < iterations; i++) {
+      const id = nanoid();
+      expect(ids.has(id)).toBe(false);
+      ids.add(id);
+    }
+    expect(ids.size).toBe(iterations);
+  });
+
+  it("should generate IDs with with given alphabet", () => {
+    const alphabet = "0123456789abcdef";
+    const id = nanoid(21, alphabet);
+    expect(id.length).toBe(21);
+    for (const char of id) expect(alphabet.includes(char)).toBe(true);
+  });
+
+  it("should avoid pool pollution, infinite loop", () => {
+    nanoid(2.1);
+    const second = nanoid();
+    const third = nanoid();
+    expect(second).not.toBe(third);
+  });
+
+  it("should have flat distribution", () => {
+    const length = 10;
+    const iterations = 100_000;
+    const charCounts: Record<string, number> = {};
+    // Initialize counts
+    for (const char of charset) {
+      charCounts[char] = 0;
+    }
+    // Generate IDs and count character occurrences
+    for (let i = 0; i < iterations; i++) {
+      const id = nanoid(length, charset);
+      for (const char of id) charCounts[char]++;
+    }
+    // Calculate expected frequency (each character should appear roughly equally)
+    const totalChars = iterations * length;
+    const expectedFrequency = totalChars / charset.length;
+    const tolerance = expectedFrequency * 0.1; // 10% tolerance
+    // Check that each character appears roughly equally
+    for (const char of charset) {
+      const actualFrequency = charCounts[char];
+      expect(actualFrequency).toBeGreaterThan(expectedFrequency - tolerance);
+      expect(actualFrequency).toBeLessThan(expectedFrequency + tolerance);
+    }
+    // Check that the distribution is uniform
+    let max = 0;
+    let min = Number.MAX_SAFE_INTEGER;
+    for (const char of charset) {
+      const observed = charCounts[char];
+      const dist = (observed * charset.length) / (iterations * length);
+      if (dist > max) max = dist;
+      if (dist < min) min = dist;
+    }
+    expect(max - min).toBeLessThan(0.05);
+  });
+});

package/tests/number.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { AbbreviationSymbols, abbreviate } from "../src/number";
+
+describe("abbreviate", () => {
+  it.each([
+    [1_742, "1.7K"],
+    [1_8364, "18.4K"],
+    [1_0701, "10.7K"],
+    [1_500_000, "1.5M"],
+    [9_876_543, "9.9M"],
+    [1_234_567_890, "1.2B"],
+    [5_876_543_210, "5.9B"],
+    [3_500_000_000_000, "3.5T"],
+    [7_654_321_987_654, "7.7T"],
+  ])("positive values: %d > %s", (value, expected) => {
+    expect(abbreviate(value)).toBe(expected);
+  });
+
+  it.each([
+    [-2_345, "-2.3K"],
+    [-15_432, "-15.4K"],
+    [-43_600, "-43.6K"],
+    [-3_892_400, "-3.9M"],
+    [-24_187_543, "-24.2M"],
+    [-4_584_321_987, "-4.6B"],
+    [-98_000_000_101, "-98.0B"],
+    [-1_700_234_567_890, "-1.7T"],
+    [-3_190_000_000_000, "-3.2T"],
+  ])("negative values: %d -> %s", (value, expected) => {
+    expect(abbreviate(value)).toBe(expected);
+  });
+
+  it("should handle custom precision", () => {
+    expect(abbreviate(1234, 0)).toBe("1K");
+    expect(abbreviate(1500, 2)).toBe("1.50K");
+    expect(abbreviate(9_876_543, 3)).toBe("9.877M");
+    expect(abbreviate(56_789, 2)).toBe("56.79K");
+    expect(abbreviate(-1_234_567, 0)).toBe("-1M");
+    expect(abbreviate(-2_345_678, 2)).toBe("-2.35M");
+  });
+
+  it("should handle custom precision options", () => {
+    expect(abbreviate(1234567, { precision: 3 })).toBe("1.235M");
+    expect(abbreviate(999500, { precision: 0 })).toBe("1M");
+    expect(abbreviate(-8765432, { precision: 2 })).toBe("-8.77M");
+  });
+
+  it("should handle custom symbols", () => {
+    const bytes_symbol: AbbreviationSymbols = {
+      B: 1,
+      KB: 1024,
+      MB: 1024 ** 2,
+      GB: 1024 ** 3,
+      TB: 1024 ** 4,
+    };
+    expect(abbreviate(1234567, { symbols: bytes_symbol })).toBe("1.2MB");
+    expect(abbreviate(999500, { symbols: bytes_symbol })).toBe("1.0MB");
+    expect(abbreviate(8765432, { symbols: bytes_symbol })).toBe("8.4MB");
+
+    const mass_symbols: AbbreviationSymbols = {
+      g: 1,
+      kg: 1e3,
+      ton: 1e6,
+    };
+    expect(abbreviate(500, { symbols: mass_symbols })).toBe("500.0g");
+    expect(abbreviate(1500, { symbols: mass_symbols })).toBe("1.5kg");
+    expect(abbreviate(1234567, { symbols: mass_symbols })).toBe("1.2ton");
+    expect(abbreviate(-1500, { symbols: mass_symbols })).toBe("-1.5kg");
+  });
+});