@ekumlin/typescript-toolkit 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+# @ekumlin/typescript-toolkit
+
+Core utility functions for TypeScript & React projects, organized by domain.
+
+## Installation
+
+```bash
+npm install @ekumlin/typescript-toolkit
+# or
+pnpm add @ekumlin/typescript-toolkit
+# or
+yarn add @ekumlin/typescript-toolkit
+```
+
+## Usage
+
+This package uses subpath exports for tree-shaking. Import only what you need:
+
+```typescript
+import { clamp, positiveModulo } from '@ekumlin/typescript-toolkit/number';
+import { isNonNullish } from '@ekumlin/typescript-toolkit/types';
+import { invariant } from '@ekumlin/typescript-toolkit/values';
+```
+
+## Available Modules
+
+### `collections`
+Array, map, and object utilities for common operations.
+
+### `dom`
+DOM manipulation and CSS helpers for browser environments.
+
+### `environment`
+Runtime environment detection utilities.
+
+### `error`
+Error handling and conversion utilities.
+
+### `http`
+HTTP-related utilities including status codes, headers, query parameters, and authorization tokens.
+
+### `io`
+Input/output constants including key codes and MIME type names.
+
+### `number`
+Math and number utilities like `clamp`, `positiveModulo`, and number conversions.
+
+### `promise`
+Promise manipulation helpers.
+
+### `routing`
+URL and routing utilities for navigation.
+
+### `string`
+String manipulation functions including `upperFirst`, `toReadableFileSize`, and URL validation.
+
+### `time`
+Date and time utilities including leap year detection, days in month calculation, and time format validation.
+
+### `types`
+Type guards for runtime type checking.
+
+### `values`
+Value assertion utilities including `invariant` and `unreachable` for runtime guarantees.
+
+## Dependencies
+
+- **zod** - Schema validation (used in type guards)
+
+## Development
+
+Build the package:
+
+```bash
+pnpm build
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+Watch mode for development:
+
+```bash
+pnpm dev
+```
+
+Type check:
+
+```bash
+pnpm lint
+```
+
+## License
+
+MIT © Eric Kumlin

package/dist/collections.d.mts

@@ -0,0 +1,7 @@
+declare const getMaxBy: <T>(items: T[], getValue: (item: T) => number) => T | undefined;
+
+declare const mapAsync: <TIn, TOut>(array: TIn[], mapAsyncFn: (v: TIn) => Promise<TOut>) => Promise<TOut[]>;
+
+declare const keysOf: <T extends object>(obj: T) => (keyof T)[];
+
+export { getMaxBy, keysOf, mapAsync };

package/dist/collections.d.ts

@@ -0,0 +1,7 @@
+declare const getMaxBy: <T>(items: T[], getValue: (item: T) => number) => T | undefined;
+
+declare const mapAsync: <TIn, TOut>(array: TIn[], mapAsyncFn: (v: TIn) => Promise<TOut>) => Promise<TOut[]>;
+
+declare const keysOf: <T extends object>(obj: T) => (keyof T)[];
+
+export { getMaxBy, keysOf, mapAsync };

package/dist/collections.js

@@ -0,0 +1,60 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/collections/index.ts
+var collections_exports = {};
+__export(collections_exports, {
+  getMaxBy: () => getMaxBy,
+  keysOf: () => keysOf,
+  mapAsync: () => mapAsync
+});
+module.exports = __toCommonJS(collections_exports);
+
+// src/collections/array.ts
+var getMaxBy = (items, getValue) => {
+  let maxValue = Number.MIN_VALUE;
+  let maxItem;
+  for (const item of items) {
+    const value = getValue(item);
+    if (value > maxValue) {
+      maxValue = value;
+      maxItem = item;
+    }
+  }
+  return maxItem;
+};
+
+// src/collections/map.ts
+var mapAsync = async (array, mapAsyncFn) => {
+  const out = [];
+  for (const element of array) {
+    out.push(await mapAsyncFn(element));
+  }
+  return out;
+};
+
+// src/collections/object.ts
+var keysOf = (obj) => Array.from(Object.keys(obj));
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getMaxBy,
+  keysOf,
+  mapAsync
+});
+//# sourceMappingURL=collections.js.map

package/dist/collections.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/collections/index.ts","../src/collections/array.ts","../src/collections/map.ts","../src/collections/object.ts"],"sourcesContent":["export * from \"./array\";\nexport * from \"./map\";\nexport * from \"./object\";\n","export const getMaxBy = <T>(\n\titems: T[],\n\tgetValue: (item: T) => number,\n): T | undefined => {\n\tlet maxValue = Number.MIN_VALUE;\n\tlet maxItem: T | undefined;\n\n\tfor (const item of items) {\n\t\tconst value = getValue(item);\n\n\t\tif (value > maxValue) {\n\t\t\tmaxValue = value;\n\t\t\tmaxItem = item;\n\t\t}\n\t}\n\n\treturn maxItem;\n};\n","export const mapAsync = async <TIn, TOut>(\n\tarray: TIn[],\n\tmapAsyncFn: (v: TIn) => Promise<TOut>,\n): Promise<TOut[]> => {\n\tconst out: TOut[] = [];\n\n\tfor (const element of array) {\n\t\tout.push(await mapAsyncFn(element));\n\t}\n\n\treturn out;\n};\n","export const keysOf = <T extends object>(obj: T): (keyof T)[] =>\n\tArray.from(Object.keys(obj)) as (keyof T)[]; // eslint-disable-line @typescript-eslint/consistent-type-assertions\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAO,IAAM,WAAW,CACvB,OACA,aACmB;AACnB,MAAI,WAAW,OAAO;AACtB,MAAI;AAEJ,aAAW,QAAQ,OAAO;AACzB,UAAM,QAAQ,SAAS,IAAI;AAE3B,QAAI,QAAQ,UAAU;AACrB,iBAAW;AACX,gBAAU;AAAA,IACX;AAAA,EACD;AAEA,SAAO;AACR;;;ACjBO,IAAM,WAAW,OACvB,OACA,eACqB;AACrB,QAAM,MAAc,CAAC;AAErB,aAAW,WAAW,OAAO;AAC5B,QAAI,KAAK,MAAM,WAAW,OAAO,CAAC;AAAA,EACnC;AAEA,SAAO;AACR;;;ACXO,IAAM,SAAS,CAAmB,QACxC,MAAM,KAAK,OAAO,KAAK,GAAG,CAAC;","names":[]}

package/dist/collections.mjs

@@ -0,0 +1,31 @@
+// src/collections/array.ts
+var getMaxBy = (items, getValue) => {
+  let maxValue = Number.MIN_VALUE;
+  let maxItem;
+  for (const item of items) {
+    const value = getValue(item);
+    if (value > maxValue) {
+      maxValue = value;
+      maxItem = item;
+    }
+  }
+  return maxItem;
+};
+
+// src/collections/map.ts
+var mapAsync = async (array, mapAsyncFn) => {
+  const out = [];
+  for (const element of array) {
+    out.push(await mapAsyncFn(element));
+  }
+  return out;
+};
+
+// src/collections/object.ts
+var keysOf = (obj) => Array.from(Object.keys(obj));
+export {
+  getMaxBy,
+  keysOf,
+  mapAsync
+};
+//# sourceMappingURL=collections.mjs.map

package/dist/collections.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/collections/array.ts","../src/collections/map.ts","../src/collections/object.ts"],"sourcesContent":["export const getMaxBy = <T>(\n\titems: T[],\n\tgetValue: (item: T) => number,\n): T | undefined => {\n\tlet maxValue = Number.MIN_VALUE;\n\tlet maxItem: T | undefined;\n\n\tfor (const item of items) {\n\t\tconst value = getValue(item);\n\n\t\tif (value > maxValue) {\n\t\t\tmaxValue = value;\n\t\t\tmaxItem = item;\n\t\t}\n\t}\n\n\treturn maxItem;\n};\n","export const mapAsync = async <TIn, TOut>(\n\tarray: TIn[],\n\tmapAsyncFn: (v: TIn) => Promise<TOut>,\n): Promise<TOut[]> => {\n\tconst out: TOut[] = [];\n\n\tfor (const element of array) {\n\t\tout.push(await mapAsyncFn(element));\n\t}\n\n\treturn out;\n};\n","export const keysOf = <T extends object>(obj: T): (keyof T)[] =>\n\tArray.from(Object.keys(obj)) as (keyof T)[]; // eslint-disable-line @typescript-eslint/consistent-type-assertions\n"],"mappings":";AAAO,IAAM,WAAW,CACvB,OACA,aACmB;AACnB,MAAI,WAAW,OAAO;AACtB,MAAI;AAEJ,aAAW,QAAQ,OAAO;AACzB,UAAM,QAAQ,SAAS,IAAI;AAE3B,QAAI,QAAQ,UAAU;AACrB,iBAAW;AACX,gBAAU;AAAA,IACX;AAAA,EACD;AAEA,SAAO;AACR;;;ACjBO,IAAM,WAAW,OACvB,OACA,eACqB;AACrB,QAAM,MAAc,CAAC;AAErB,aAAW,WAAW,OAAO;AAC5B,QAAI,KAAK,MAAM,WAAW,OAAO,CAAC;AAAA,EACnC;AAEA,SAAO;AACR;;;ACXO,IAAM,SAAS,CAAmB,QACxC,MAAM,KAAK,OAAO,KAAK,GAAG,CAAC;","names":[]}

package/dist/dom.d.mts

@@ -0,0 +1,161 @@
+import z from 'zod';
+
+declare const htmlColorNamesSchema: z.ZodEnum<{
+    aliceBlue: "aliceBlue";
+    antiqueWhite: "antiqueWhite";
+    aqua: "aqua";
+    aquamarine: "aquamarine";
+    azure: "azure";
+    beige: "beige";
+    bisque: "bisque";
+    black: "black";
+    blanchedAlmond: "blanchedAlmond";
+    blue: "blue";
+    blueViolet: "blueViolet";
+    brown: "brown";
+    burlyWood: "burlyWood";
+    cadetBlue: "cadetBlue";
+    chartreuse: "chartreuse";
+    chocolate: "chocolate";
+    coral: "coral";
+    cornflowerBlue: "cornflowerBlue";
+    cornsilk: "cornsilk";
+    crimson: "crimson";
+    cyan: "cyan";
+    darkBlue: "darkBlue";
+    darkCyan: "darkCyan";
+    darkGoldenRod: "darkGoldenRod";
+    darkGrey: "darkGrey";
+    darkGreen: "darkGreen";
+    darkKhaki: "darkKhaki";
+    darkMagenta: "darkMagenta";
+    darkOliveGreen: "darkOliveGreen";
+    darkOrange: "darkOrange";
+    darkOrchid: "darkOrchid";
+    darkRed: "darkRed";
+    darkSalmon: "darkSalmon";
+    darkSeaGreen: "darkSeaGreen";
+    darkSlateBlue: "darkSlateBlue";
+    darkSlateGrey: "darkSlateGrey";
+    darkTurquoise: "darkTurquoise";
+    darkViolet: "darkViolet";
+    deepPink: "deepPink";
+    deepSkyBlue: "deepSkyBlue";
+    dimGray: "dimGray";
+    dodgerBlue: "dodgerBlue";
+    fireBrick: "fireBrick";
+    floralWhite: "floralWhite";
+    forestGreen: "forestGreen";
+    fuchsia: "fuchsia";
+    gainsboro: "gainsboro";
+    ghostWhite: "ghostWhite";
+    gold: "gold";
+    goldenRod: "goldenRod";
+    grey: "grey";
+    green: "green";
+    greenYellow: "greenYellow";
+    honeyDew: "honeyDew";
+    hotPink: "hotPink";
+    indianRed: "indianRed";
+    indigo: "indigo";
+    ivory: "ivory";
+    khaki: "khaki";
+    lavender: "lavender";
+    lavenderBlush: "lavenderBlush";
+    lawnGreen: "lawnGreen";
+    lemonChiffon: "lemonChiffon";
+    lightBlue: "lightBlue";
+    lightCoral: "lightCoral";
+    lightCyan: "lightCyan";
+    lightGoldenRodYellow: "lightGoldenRodYellow";
+    lightGrey: "lightGrey";
+    lightGreen: "lightGreen";
+    lightPink: "lightPink";
+    lightSalmon: "lightSalmon";
+    lightSeaGreen: "lightSeaGreen";
+    lightSkyBlue: "lightSkyBlue";
+    lightSlateGrey: "lightSlateGrey";
+    lightSteelBlue: "lightSteelBlue";
+    lightYellow: "lightYellow";
+    lime: "lime";
+    limeGreen: "limeGreen";
+    linen: "linen";
+    magenta: "magenta";
+    maroon: "maroon";
+    mediumAquaMarine: "mediumAquaMarine";
+    mediumBlue: "mediumBlue";
+    mediumOrchid: "mediumOrchid";
+    mediumPurple: "mediumPurple";
+    mediumSeaGreen: "mediumSeaGreen";
+    mediumSlateBlue: "mediumSlateBlue";
+    mediumSpringGreen: "mediumSpringGreen";
+    mediumTurquoise: "mediumTurquoise";
+    mediumVioletRed: "mediumVioletRed";
+    midnightBlue: "midnightBlue";
+    mintCream: "mintCream";
+    mistyRose: "mistyRose";
+    moccasin: "moccasin";
+    navajoWhite: "navajoWhite";
+    navy: "navy";
+    oldLace: "oldLace";
+    olive: "olive";
+    oliveDrab: "oliveDrab";
+    orange: "orange";
+    orangeRed: "orangeRed";
+    orchid: "orchid";
+    paleGoldenRod: "paleGoldenRod";
+    paleGreen: "paleGreen";
+    paleTurquoise: "paleTurquoise";
+    paleVioletRed: "paleVioletRed";
+    papayaWhip: "papayaWhip";
+    peachPuff: "peachPuff";
+    peru: "peru";
+    pink: "pink";
+    plum: "plum";
+    powderBlue: "powderBlue";
+    purple: "purple";
+    red: "red";
+    rosyBrown: "rosyBrown";
+    royalBlue: "royalBlue";
+    saddleBrown: "saddleBrown";
+    salmon: "salmon";
+    sandyBrown: "sandyBrown";
+    seaGreen: "seaGreen";
+    seaShell: "seaShell";
+    sienna: "sienna";
+    silver: "silver";
+    skyBlue: "skyBlue";
+    slateBlue: "slateBlue";
+    slateGrey: "slateGrey";
+    snow: "snow";
+    springGreen: "springGreen";
+    steelBlue: "steelBlue";
+    tan: "tan";
+    teal: "teal";
+    thistle: "thistle";
+    tomato: "tomato";
+    turquoise: "turquoise";
+    violet: "violet";
+    wheat: "wheat";
+    white: "white";
+    whiteSmoke: "whiteSmoke";
+    yellow: "yellow";
+    yellowGreen: "yellowGreen";
+}>;
+type HtmlColorName = z.infer<typeof htmlColorNamesSchema>;
+declare const asHtmlColorName: (value: unknown) => HtmlColorName;
+declare const isHtmlColorName: (obj: unknown) => obj is HtmlColorName;
+type CssVariable = `var(--${string})`;
+declare const isCssVariable: (obj: unknown) => obj is CssVariable;
+type CssVariableColor = CssVariable | `rgb(${CssVariable})` | `rgba(${CssVariable})`;
+declare const isCssVariableColor: (obj: unknown) => obj is CssVariableColor;
+type HexColor = `#${string}`;
+declare const isHexColor: (obj: unknown) => obj is HexColor;
+type RgbaColor = `rgba(${number}, ${number}, ${number}, ${number})`;
+declare const isRgbaColor: (obj: unknown) => obj is RgbaColor;
+type RgbColor = `rgb(${number}, ${number}, ${number})`;
+declare const isRgbColor: (obj: unknown) => obj is RgbColor;
+type HtmlColor = HtmlColorName | CssVariableColor | RgbColor | RgbaColor | HexColor;
+declare const isHtmlColor: (obj: unknown) => obj is HtmlColor;
+
+export { type CssVariable, type CssVariableColor, type HexColor, type HtmlColor, type HtmlColorName, type RgbColor, type RgbaColor, asHtmlColorName, htmlColorNamesSchema, isCssVariable, isCssVariableColor, isHexColor, isHtmlColor, isHtmlColorName, isRgbColor, isRgbaColor };

package/dist/dom.d.ts

@@ -0,0 +1,161 @@
+import z from 'zod';
+
+declare const htmlColorNamesSchema: z.ZodEnum<{
+    aliceBlue: "aliceBlue";
+    antiqueWhite: "antiqueWhite";
+    aqua: "aqua";
+    aquamarine: "aquamarine";
+    azure: "azure";
+    beige: "beige";
+    bisque: "bisque";
+    black: "black";
+    blanchedAlmond: "blanchedAlmond";
+    blue: "blue";
+    blueViolet: "blueViolet";
+    brown: "brown";
+    burlyWood: "burlyWood";
+    cadetBlue: "cadetBlue";
+    chartreuse: "chartreuse";
+    chocolate: "chocolate";
+    coral: "coral";
+    cornflowerBlue: "cornflowerBlue";
+    cornsilk: "cornsilk";
+    crimson: "crimson";
+    cyan: "cyan";
+    darkBlue: "darkBlue";
+    darkCyan: "darkCyan";
+    darkGoldenRod: "darkGoldenRod";
+    darkGrey: "darkGrey";
+    darkGreen: "darkGreen";
+    darkKhaki: "darkKhaki";
+    darkMagenta: "darkMagenta";
+    darkOliveGreen: "darkOliveGreen";
+    darkOrange: "darkOrange";
+    darkOrchid: "darkOrchid";
+    darkRed: "darkRed";
+    darkSalmon: "darkSalmon";
+    darkSeaGreen: "darkSeaGreen";
+    darkSlateBlue: "darkSlateBlue";
+    darkSlateGrey: "darkSlateGrey";
+    darkTurquoise: "darkTurquoise";
+    darkViolet: "darkViolet";
+    deepPink: "deepPink";
+    deepSkyBlue: "deepSkyBlue";
+    dimGray: "dimGray";
+    dodgerBlue: "dodgerBlue";
+    fireBrick: "fireBrick";
+    floralWhite: "floralWhite";
+    forestGreen: "forestGreen";
+    fuchsia: "fuchsia";
+    gainsboro: "gainsboro";
+    ghostWhite: "ghostWhite";
+    gold: "gold";
+    goldenRod: "goldenRod";
+    grey: "grey";
+    green: "green";
+    greenYellow: "greenYellow";
+    honeyDew: "honeyDew";
+    hotPink: "hotPink";
+    indianRed: "indianRed";
+    indigo: "indigo";
+    ivory: "ivory";
+    khaki: "khaki";
+    lavender: "lavender";
+    lavenderBlush: "lavenderBlush";
+    lawnGreen: "lawnGreen";
+    lemonChiffon: "lemonChiffon";
+    lightBlue: "lightBlue";
+    lightCoral: "lightCoral";
+    lightCyan: "lightCyan";
+    lightGoldenRodYellow: "lightGoldenRodYellow";
+    lightGrey: "lightGrey";
+    lightGreen: "lightGreen";
+    lightPink: "lightPink";
+    lightSalmon: "lightSalmon";
+    lightSeaGreen: "lightSeaGreen";
+    lightSkyBlue: "lightSkyBlue";
+    lightSlateGrey: "lightSlateGrey";
+    lightSteelBlue: "lightSteelBlue";
+    lightYellow: "lightYellow";
+    lime: "lime";
+    limeGreen: "limeGreen";
+    linen: "linen";
+    magenta: "magenta";
+    maroon: "maroon";
+    mediumAquaMarine: "mediumAquaMarine";
+    mediumBlue: "mediumBlue";
+    mediumOrchid: "mediumOrchid";
+    mediumPurple: "mediumPurple";
+    mediumSeaGreen: "mediumSeaGreen";
+    mediumSlateBlue: "mediumSlateBlue";
+    mediumSpringGreen: "mediumSpringGreen";
+    mediumTurquoise: "mediumTurquoise";
+    mediumVioletRed: "mediumVioletRed";
+    midnightBlue: "midnightBlue";
+    mintCream: "mintCream";
+    mistyRose: "mistyRose";
+    moccasin: "moccasin";
+    navajoWhite: "navajoWhite";
+    navy: "navy";
+    oldLace: "oldLace";
+    olive: "olive";
+    oliveDrab: "oliveDrab";
+    orange: "orange";
+    orangeRed: "orangeRed";
+    orchid: "orchid";
+    paleGoldenRod: "paleGoldenRod";
+    paleGreen: "paleGreen";
+    paleTurquoise: "paleTurquoise";
+    paleVioletRed: "paleVioletRed";
+    papayaWhip: "papayaWhip";
+    peachPuff: "peachPuff";
+    peru: "peru";
+    pink: "pink";
+    plum: "plum";
+    powderBlue: "powderBlue";
+    purple: "purple";
+    red: "red";
+    rosyBrown: "rosyBrown";
+    royalBlue: "royalBlue";
+    saddleBrown: "saddleBrown";
+    salmon: "salmon";
+    sandyBrown: "sandyBrown";
+    seaGreen: "seaGreen";
+    seaShell: "seaShell";
+    sienna: "sienna";
+    silver: "silver";
+    skyBlue: "skyBlue";
+    slateBlue: "slateBlue";
+    slateGrey: "slateGrey";
+    snow: "snow";
+    springGreen: "springGreen";
+    steelBlue: "steelBlue";
+    tan: "tan";
+    teal: "teal";
+    thistle: "thistle";
+    tomato: "tomato";
+    turquoise: "turquoise";
+    violet: "violet";
+    wheat: "wheat";
+    white: "white";
+    whiteSmoke: "whiteSmoke";
+    yellow: "yellow";
+    yellowGreen: "yellowGreen";
+}>;
+type HtmlColorName = z.infer<typeof htmlColorNamesSchema>;
+declare const asHtmlColorName: (value: unknown) => HtmlColorName;
+declare const isHtmlColorName: (obj: unknown) => obj is HtmlColorName;
+type CssVariable = `var(--${string})`;
+declare const isCssVariable: (obj: unknown) => obj is CssVariable;
+type CssVariableColor = CssVariable | `rgb(${CssVariable})` | `rgba(${CssVariable})`;
+declare const isCssVariableColor: (obj: unknown) => obj is CssVariableColor;
+type HexColor = `#${string}`;
+declare const isHexColor: (obj: unknown) => obj is HexColor;
+type RgbaColor = `rgba(${number}, ${number}, ${number}, ${number})`;
+declare const isRgbaColor: (obj: unknown) => obj is RgbaColor;
+type RgbColor = `rgb(${number}, ${number}, ${number})`;
+declare const isRgbColor: (obj: unknown) => obj is RgbColor;
+type HtmlColor = HtmlColorName | CssVariableColor | RgbColor | RgbaColor | HexColor;
+declare const isHtmlColor: (obj: unknown) => obj is HtmlColor;
+
+export { type CssVariable, type CssVariableColor, type HexColor, type HtmlColor, type HtmlColorName, type RgbColor, type RgbaColor, asHtmlColorName, htmlColorNamesSchema, isCssVariable, isCssVariableColor, isHexColor, isHtmlColor, isHtmlColorName, isRgbColor, isRgbaColor };