Philosophy

• Minimal — Each package does one thing well with minimal dependencies.
• Type-safe — Full TypeScript support with strict mode enabled.
• Tested — 80%+ code coverage required for all packages.
• Consistent — Unified code style, structure, and tooling across all packages.

Each package is published under the @simpill scope on npm. Source code lives in separate GitHub repositories; this repo is the landing page and index.

Repositories

Each package has its own repository. Click through for source, README, and contribution instructions.

| Package | Description | Status | |---------|-------------|--------| | adapters.utils | Adapter helpers, logger and cache adapter interfaces (Node and Edge). | New | | algorithms.utils | Algorithms: stable merge sort, quick sort, binary search, lower/upper bound (Node and Edge). | New | | annotations.utils | Typed metadata store and annotation helpers for symbols and keys (Node and Edge). | New | | api.utils | Typed API client with Zod validation, handler registry, and middleware (Node and Edge). | New | | array.utils | Array utilities: unique, chunk, compact, groupBy, sortBy, flattenOnce (Node and Edge). | New | | async.utils | Retry failed promises with timeout, delay, and backoff; limit concurrency with Semaphore (Node and Edge). | New | | cache.utils | In-memory LRU and TTL cache with memoize; small and tree-shakeable (Node and Edge). | New | | collections.utils | Type-safe LinkedList, Queue, Stack, LRU/TTL, MultiMap, BiMap—no full collections lib (Node and Edge). | New | | crypto.utils | Hash, randomBytes, and timing-safe compare for Node.js. | New | | data.utils | Data utilities: validate, prepare, lifecycle, extend, config (Node and Edge). | New | | env.utils | Lightweight, type-safe environment variable utilities for Node.js and Edge Runtime. | Stable | | enum.utils | Enum helpers: getEnumValue, isValidEnumValue, EnumHelper (Node and Edge). | New | | errors.utils | Typed error classes, error codes, and serializeError for logging and RPC (Node and Edge). | New | | events.utils | PubSub, observer, and typed event emitter (Node and Edge). | New | | factories.utils | Typed factory builder, singleton factory, and error factory helpers (Node and Edge). | New | | file.utils | Typed file I/O: readFileUtf8, readFileJson, writeFile, ensureDir for Node.js. | New | | function.utils | Debounce, throttle, once, pipe, and compose with TypeScript inference (Node and Edge). | New | | http.utils | Fetch with timeout, retry, and typed HTTP client—no axios required (Node and Edge). | New | | ai-image-generated-ai-cli | Image AI toolkit: core SDK, CLI (ai-image-gen), and prompt discovery web UI (Gemini, OpenAI, xAI). | New | | logger.utils | Lightweight, type-safe structured logging with correlation context for Node.js and Edge Runtime. | In Development | | middleware.utils | Framework-agnostic middleware types and correlation ID middleware (Node and Edge). | New | | misc.utils | Backend misc: singleton, debounce, throttle, LRU, polling, intervals, enums, once, memoize (Node and Edge). | New | | nextjs.utils | Next.js App Router helpers: safe server actions, route handlers, request context, middleware. | New | | number.utils | Number utilities: clamp, roundTo, toInt/Float, isInRange, lerp, sum, avg (Node and Edge). | New | | object.utils | Type-safe object utilities: pick, omit, merge, get/set by path, guards (Node and Edge). | Stable | | observability.utils | Single integration surface for correlation middleware, request context, and logger (Node). | New | | patterns.utils | Composable design patterns: Result/Either, strategySelector, pipeAsync (Node and Edge). | New | | protocols.utils | Shared protocol constants and types for HTTP, correlation, and env parsing (Node and Edge). | New | | react.utils | Framework-agnostic React utilities: hooks, safe context, stable callbacks, transitions. | New | | request-context.utils | AsyncLocalStorage request context (requestId, traceId) for Node.js logging and tracing. | New | | resilience.utils | Circuit breaker, rate limiter, bulkhead, and jittered backoff for fault-tolerant APIs (Node and Edge). | New | | socket.utils | Reconnecting WebSocket client with optional heartbeat (Node and Edge). | New | | string.utils | String utilities: formatting, casing, trim, slugify (Node and Edge). | New | | test.utils | Test patterns, faker wrapper, enricher, and test-runner helpers (Node and Edge). | New | | time.utils | Time utilities: debounce, throttle, interval manager, managed timeout (Node and Edge). | Stable | | token-optimizer.utils | Token optimization utilities: cleaning, strategies, telemetry (Node and Edge). | New | | uuid.utils | Generate and validate UUIDs (v1/v4/v5) with full TypeScript support (Node and Edge). | Stable | | zod.utils | Zod schema helpers: builders, safe-parse, transforms, OpenAPI metadata (Node and Edge). | New | | zustand.utils | Zustand store helpers: factory, persist, devtools, slices (Node and Edge). | New |

Quick Start

Install any package from npm:

npm install @simpill/env.utils
npm install @simpill/logger.utils
npm install @simpill/cache.utils
npm install @simpill/async.utils
npm install @simpill/function.utils
npm install @simpill/string.utils

Use the Repositories table above to open a package’s GitHub repo for docs, API reference, and examples.

Consumption: Every package is consumable separately (npm or github:SkinnnyJay/<repo>) and via @simpill/utils (run npm install at root; all packages land in node_modules). Run npm run verify:deps to confirm. No utils/ folder is required—package source lives in the GitHub repos above; this repo pulls them in via dependencies. You can remove utils/ if present.

Use the main repo in another project

The main project references all util packages via GitHub. To pull in the full set of utils from this repo into another project, add the monorepo as a dependency:

npm install github:SkinnnyJay/simpill-utils

(or add "@simpill/utils": "github:SkinnnyJay/simpill-utils" to your package.json). Installing it will fetch each util from its GitHub repo (github:SkinnnyJay/adapters.utils, etc.) so you can import any util in your code:

import { createAdapter } from "@simpill/adapters.utils";
import { unique } from "@simpill/array.utils";
import { getEnvString } from "@simpill/env.utils";

To depend on only one util, install that package from npm or GitHub (e.g. npm install @simpill/adapters.utils or npm install github:SkinnnyJay/adapters.utils).

Using @simpill/utils (this repo)

Clone and install from the repo root. All @simpill utils are installed from GitHub into node_modules and are usable as-is (e.g. @simpill/env.utils ships dist/ in its repo):

npm install

Then any script or app at the repo root can require/import them, e.g.:

const { getEdgeString } = require("@simpill/env.utils/client");
const { unique } = require("@simpill/array.utils");

To confirm all installed packages are resolvable and load correctly:

npm run verify:deps
npm test

npm test imports all 38 @simpill packages and prints NODE_ENV; if any package failed to install (e.g. empty folder), re-run npm install or rm -rf node_modules && npm install.

Sandbox apps (e.g. todo-app) live in a separate repo: simpill-sandbox. To develop individual util packages, clone their GitHub repos (see Repositories table).

Discoverability

• GitHub: Add topics (e.g. simpill, typescript, utilities, nodejs, edge-runtime) so the org and repos appear in search. See .github/TOPICS.md for a full list.
• npm: Every package lists simpill and package-specific keywords. Use npm search simpill to find all published packages.

Documentation

• CONTRIBUTING.md — How to create and maintain packages (and where they live).

Credits and inspiration

We build on and are inspired by the following projects and standards.

Dependencies

Packages depend on these core libraries (each link goes to the official repository):

| Library | Use in @simpill | Repository | |--------|------------------|------------| | Zod | Schema validation, API types, safe parsing | colinhacks/zod | | Zustand | Store factory, persist, devtools | pmndrs/zustand | | Next.js | App Router, server actions, middleware | vercel/next.js | | React | Hooks, context, transitions | facebook/react | | uuid | UUID v1/v4/v5 generation and validation | uuidjs/uuid | | Faker | Test data and mocks | faker-js/faker | | Biome | Linting and formatting (dev) | biomejs/biome | | Jest | Unit and integration tests (dev) | jestjs/jest | | TypeScript | Type checking and emit | microsoft/TypeScript |

Inspiration and prior art

• Lodash — Array, object, and function utility patterns.
• Vercel — Next.js, t3-env, and server/edge patterns.
• Node.js — AsyncLocalStorage, fs, and runtime separation.
• RFC 4122 — UUID specification.
• TC39 — ECMAScript and standard library evolution.

License

ISC