@simpill/utils 1.0.0

package/README.md

@@ -0,0 +1,186 @@
+<p align="center">
+  <img src="./logo.png" alt="@simpill" width="100%" />
+</p>
+
+<p align="center">
+  <strong>A collection of lightweight, type-safe TypeScript utility packages for modern JavaScript applications.</strong>
+</p>
+
+<p align="center">
+  <a href="#philosophy">Philosophy</a> •
+  <a href="#repositories">Repositories</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#discoverability">Discoverability</a> •
+  <a href="#credits-and-inspiration">Credits</a>
+</p>
+
+---
+
+## 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**](https://github.com/SkinnnyJay/adapters.utils) | Adapter helpers, logger and cache adapter interfaces (Node and Edge). | New |
+| [**algorithms.utils**](https://github.com/SkinnnyJay/algorithms.utils) | Algorithms: stable merge sort, quick sort, binary search, lower/upper bound (Node and Edge). | New |
+| [**annotations.utils**](https://github.com/SkinnnyJay/annotations.utils) | Typed metadata store and annotation helpers for symbols and keys (Node and Edge). | New |
+| [**api.utils**](https://github.com/SkinnnyJay/api.utils) | Typed API client with Zod validation, handler registry, and middleware (Node and Edge). | New |
+| [**array.utils**](https://github.com/SkinnnyJay/array.utils) | Array utilities: unique, chunk, compact, groupBy, sortBy, flattenOnce (Node and Edge). | New |
+| [**async.utils**](https://github.com/SkinnnyJay/async.utils) | Retry failed promises with timeout, delay, and backoff; limit concurrency with Semaphore (Node and Edge). | New |
+| [**cache.utils**](https://github.com/SkinnnyJay/cache.utils) | In-memory LRU and TTL cache with memoize; small and tree-shakeable (Node and Edge). | New |
+| [**collections.utils**](https://github.com/SkinnnyJay/collections.utils) | Type-safe LinkedList, Queue, Stack, LRU/TTL, MultiMap, BiMap—no full collections lib (Node and Edge). | New |
+| [**crypto.utils**](https://github.com/SkinnnyJay/crypto.utils) | Hash, randomBytes, and timing-safe compare for Node.js. | New |
+| [**data.utils**](https://github.com/SkinnnyJay/data.utils) | Data utilities: validate, prepare, lifecycle, extend, config (Node and Edge). | New |
+| [**env.utils**](https://github.com/SkinnnyJay/env.utils) | Lightweight, type-safe environment variable utilities for Node.js and Edge Runtime. | Stable |
+| [**enum.utils**](https://github.com/SkinnnyJay/enum.utils) | Enum helpers: getEnumValue, isValidEnumValue, EnumHelper (Node and Edge). | New |
+| [**errors.utils**](https://github.com/SkinnnyJay/errors.utils) | Typed error classes, error codes, and serializeError for logging and RPC (Node and Edge). | New |
+| [**events.utils**](https://github.com/SkinnnyJay/events.utils) | PubSub, observer, and typed event emitter (Node and Edge). | New |
+| [**factories.utils**](https://github.com/SkinnnyJay/factories.utils) | Typed factory builder, singleton factory, and error factory helpers (Node and Edge). | New |
+| [**file.utils**](https://github.com/SkinnnyJay/file.utils) | Typed file I/O: readFileUtf8, readFileJson, writeFile, ensureDir for Node.js. | New |
+| [**function.utils**](https://github.com/SkinnnyJay/function.utils) | Debounce, throttle, once, pipe, and compose with TypeScript inference (Node and Edge). | New |
+| [**http.utils**](https://github.com/SkinnnyJay/http.utils) | Fetch with timeout, retry, and typed HTTP client—no axios required (Node and Edge). | New |
+| [**ai-image-generated-ai-cli**](https://github.com/simpill/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**](https://github.com/SkinnnyJay/logger.utils) | Lightweight, type-safe structured logging with correlation context for Node.js and Edge Runtime. | In Development |
+| [**middleware.utils**](https://github.com/SkinnnyJay/middleware.utils) | Framework-agnostic middleware types and correlation ID middleware (Node and Edge). | New |
+| [**misc.utils**](https://github.com/SkinnnyJay/misc.utils) | Backend misc: singleton, debounce, throttle, LRU, polling, intervals, enums, once, memoize (Node and Edge). | New |
+| [**nextjs.utils**](https://github.com/SkinnnyJay/nextjs.utils) | Next.js App Router helpers: safe server actions, route handlers, request context, middleware. | New |
+| [**number.utils**](https://github.com/SkinnnyJay/number.utils) | Number utilities: clamp, roundTo, toInt/Float, isInRange, lerp, sum, avg (Node and Edge). | New |
+| [**object.utils**](https://github.com/SkinnnyJay/object.utils) | Type-safe object utilities: pick, omit, merge, get/set by path, guards (Node and Edge). | Stable |
+| [**observability.utils**](https://github.com/SkinnnyJay/observability.utils) | Single integration surface for correlation middleware, request context, and logger (Node). | New |
+| [**patterns.utils**](https://github.com/SkinnnyJay/patterns.utils) | Composable design patterns: Result/Either, strategySelector, pipeAsync (Node and Edge). | New |
+| [**protocols.utils**](https://github.com/SkinnnyJay/protocols.utils) | Shared protocol constants and types for HTTP, correlation, and env parsing (Node and Edge). | New |
+| [**react.utils**](https://github.com/SkinnnyJay/react.utils) | Framework-agnostic React utilities: hooks, safe context, stable callbacks, transitions. | New |
+| [**request-context.utils**](https://github.com/SkinnnyJay/request-context.utils) | AsyncLocalStorage request context (requestId, traceId) for Node.js logging and tracing. | New |
+| [**resilience.utils**](https://github.com/SkinnnyJay/resilience.utils) | Circuit breaker, rate limiter, bulkhead, and jittered backoff for fault-tolerant APIs (Node and Edge). | New |
+| [**socket.utils**](https://github.com/SkinnnyJay/socket.utils) | Reconnecting WebSocket client with optional heartbeat (Node and Edge). | New |
+| [**string.utils**](https://github.com/SkinnnyJay/string.utils) | String utilities: formatting, casing, trim, slugify (Node and Edge). | New |
+| [**test.utils**](https://github.com/SkinnnyJay/test.utils) | Test patterns, faker wrapper, enricher, and test-runner helpers (Node and Edge). | New |
+| [**time.utils**](https://github.com/SkinnnyJay/time.utils) | Time utilities: debounce, throttle, interval manager, managed timeout (Node and Edge). | Stable |
+| [**token-optimizer.utils**](https://github.com/SkinnnyJay/token-optimizer.utils) | Token optimization utilities: cleaning, strategies, telemetry (Node and Edge). | New |
+| [**uuid.utils**](https://github.com/SkinnnyJay/uuid.utils) | Generate and validate UUIDs (v1/v4/v5) with full TypeScript support (Node and Edge). | Stable |
+| [**zod.utils**](https://github.com/SkinnnyJay/zod.utils) | Zod schema helpers: builders, safe-parse, transforms, OpenAPI metadata (Node and Edge). | New |
+| [**zustand.utils**](https://github.com/SkinnnyJay/zustand.utils) | Zustand store helpers: factory, persist, devtools, slices (Node and Edge). | New |
+
+---
+
+## Quick Start
+
+Install any package from npm:
+
+```bash
+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:
+
+```bash
+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:
+
+```ts
+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):
+
+```bash
+npm install
+```
+
+Then any script or app at the repo root can require/import them, e.g.:
+
+```js
+const { getEdgeString } = require("@simpill/env.utils/client");
+const { unique } = require("@simpill/array.utils");
+```
+
+To confirm all installed packages are resolvable and load correctly:
+
+```bash
+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](https://github.com/simpill/simpill-sandbox). To develop individual util packages, clone their GitHub repos (see [Repositories](#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](./.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](./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](https://github.com/colinhacks/zod) | Schema validation, API types, safe parsing | [colinhacks/zod](https://github.com/colinhacks/zod) |
+| [Zustand](https://github.com/pmndrs/zustand) | Store factory, persist, devtools | [pmndrs/zustand](https://github.com/pmndrs/zustand) |
+| [Next.js](https://github.com/vercel/next.js) | App Router, server actions, middleware | [vercel/next.js](https://github.com/vercel/next.js) |
+| [React](https://github.com/facebook/react) | Hooks, context, transitions | [facebook/react](https://github.com/facebook/react) |
+| [uuid](https://github.com/uuidjs/uuid) | UUID v1/v4/v5 generation and validation | [uuidjs/uuid](https://github.com/uuidjs/uuid) |
+| [Faker](https://github.com/faker-js/faker) | Test data and mocks | [faker-js/faker](https://github.com/faker-js/faker) |
+| [Biome](https://github.com/biomejs/biome) | Linting and formatting (dev) | [biomejs/biome](https://github.com/biomejs/biome) |
+| [Jest](https://github.com/jestjs/jest) | Unit and integration tests (dev) | [jestjs/jest](https://github.com/jestjs/jest) |
+| [TypeScript](https://github.com/microsoft/TypeScript) | Type checking and emit | [microsoft/TypeScript](https://github.com/microsoft/TypeScript) |
+
+### Inspiration and prior art
+
+- [Lodash](https://github.com/lodash/lodash) — Array, object, and function utility patterns.
+- [Vercel](https://github.com/vercel) — Next.js, [t3-env](https://github.com/t3-oss/t3-env), and server/edge patterns.
+- [Node.js](https://github.com/nodejs/node) — [AsyncLocalStorage](https://nodejs.org/api/async_context.html#class-asynclocalstorage), `fs`, and runtime separation.
+- [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) — UUID specification.
+- [TC39](https://github.com/tc39) — ECMAScript and standard library evolution.
+
+---
+
+## License
+
+ISC

package/__tests__/README.md

@@ -0,0 +1,32 @@
+# Monorepo tests
+
+Vitest runs unit, integration, and e2e tests for the @simpill monorepo.
+
+## Prerequisites
+
+- Run `npm install` at repo root so all `@simpill/*` packages and devDependencies (vitest, vite, typescript, tsx, std-env) are installed.
+- **To run root build, test.ts (smoke), and Vitest against built packages:** root normally installs packages from GitHub (which may not include built `dist/`). To use your local utils instead:
+  1. `npm run utils:prepare` — build all utils packages (install, audit, typecheck, test, build).
+  2. `npm run use:local` — point root at `file:./utils/@simpill-*.utils` and run `npm install`.
+  3. Then `npm run build`, `npm run test:smoke`, and `npm test` use the local built packages.
+- To restore root to GitHub deps: `npm run sync:deps`, then `npm install`.
+
+## Commands
+
+From repo root:
+
+- `npm test` — run all tests
+- `npm run test:unit` — `__tests__/unit` only
+- `npm run test:integration` — `__tests__/integration` only
+- `npm run test:e2e` — `__tests__/e2e` only
+
+## Layout
+
+- **unit** — per-package resolution and behavior: `__tests__/unit/@simpill/<package>/`.
+- **unit/_resolver** — dynamic resolution of packages that do not have a dedicated unit test file.
+- **integration** — cross-package flows (e.g. env + async, errors + uuid, object + array).
+- **e2e** — critical path: core packages resolve and work together (env, uuid, object, array, errors, time).
+
+## Config
+
+`vitest.config.ts` at repo root: Node environment, globals, `__tests__/**/*.test.ts`.

package/__tests__/e2e/all-packages-resolve.e2e.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { getEdgeString } from "@simpill/env.utils/client";
+import * as Env from "@simpill/env.utils";
+import * as Uuid from "@simpill/uuid.utils";
+import * as ObjectUtils from "@simpill/object.utils";
+import * as Async from "@simpill/async.utils";
+import * as ArrayUtils from "@simpill/array.utils";
+import * as Errors from "@simpill/errors.utils";
+import * as Time from "@simpill/time.utils";
+
+describe("E2E: all critical packages resolve and work", () => {
+  it("env client getEdgeString returns string", () => {
+    expect(getEdgeString("NODE_ENV", "development")).toBeDefined();
+  });
+
+  it("all listed packages are non-null", () => {
+    const packages: Record<string, unknown> = {
+      Env,
+      Uuid,
+      ObjectUtils,
+      Async,
+      ArrayUtils,
+      Errors,
+      Time,
+    };
+    for (const [name, mod] of Object.entries(packages)) {
+      expect(mod, `Package ${name} should resolve`).not.toBeNull();
+      expect(mod, `Package ${name} should be object`).toBeDefined();
+    }
+  });
+
+  it("cross-package flow: uuid in object pick and array unique", () => {
+    const id = Uuid.generateUUID();
+    const record = { id, name: "a" };
+    const picked = ObjectUtils.pick(record, ["id"]);
+    const keys = ArrayUtils.unique(Object.keys(picked));
+    expect(keys).toContain("id");
+    expect(Uuid.isUUID(picked.id as string)).toBe(true);
+  });
+});

package/__tests__/integration/env-and-async.integration.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { getEdgeString } from "@simpill/env.utils/client";
+import { delay } from "@simpill/async.utils";
+
+describe("env.utils + async.utils integration", () => {
+  it("env value is string and delay completes", async () => {
+    const envVal = getEdgeString("NODE_ENV", "test");
+    expect(typeof envVal).toBe("string");
+    await delay(5);
+    expect(envVal).toBeDefined();
+  });
+});

package/__tests__/integration/errors-and-uuid.integration.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { serializeError, AppError } from "@simpill/errors.utils";
+import { generateUUID, isUUID } from "@simpill/uuid.utils";
+
+describe("errors.utils + uuid.utils integration", () => {
+  it("serializeError and generateUUID work together", () => {
+    const id = generateUUID();
+    expect(isUUID(id)).toBe(true);
+    const err = new AppError("test", { code: "E_TEST", meta: { requestId: id } });
+    const serialized = serializeError(err);
+    expect(serialized).toBeDefined();
+    expect(typeof serialized).toBe("object");
+  });
+});

package/__tests__/integration/object-and-array.integration.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { pick } from "@simpill/object.utils";
+import { unique, chunk } from "@simpill/array.utils";
+
+describe("object.utils + array.utils integration", () => {
+  it("pick then unique keys and chunk work together", () => {
+    const obj = { a: 1, b: 2, c: 3 };
+    const picked = pick(obj, ["a", "c"]);
+    const keys = unique(Object.keys(picked));
+    expect(keys).toHaveLength(2);
+    const chunks = chunk(keys, 1);
+    expect(chunks).toHaveLength(2);
+    expect(chunks.flat()).toEqual(keys);
+  });
+});

package/__tests__/unit/@simpill/_resolver/resolve-packages.unit.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Ensures all monolith @simpill packages resolve (types + runtime).
+ * Packages with dedicated unit tests are not re-imported here.
+ */
+import { describe, expect, it } from "vitest";
+
+const PACKAGES_TO_RESOLVE: Array<{ name: string; loader: () => Promise<Record<string, unknown>> }> = [
+  { name: "adapters.utils", loader: () => import("@simpill/adapters.utils") },
+  { name: "algorithms.utils", loader: () => import("@simpill/algorithms.utils") },
+  { name: "annotations.utils", loader: () => import("@simpill/annotations.utils") },
+  { name: "api.utils", loader: () => import("@simpill/api.utils") },
+  { name: "collections.utils", loader: () => import("@simpill/collections.utils") },
+  { name: "crypto.utils", loader: () => import("@simpill/crypto.utils") },
+  { name: "data.utils", loader: () => import("@simpill/data.utils") },
+  { name: "enum.utils", loader: () => import("@simpill/enum.utils") },
+  { name: "events.utils", loader: () => import("@simpill/events.utils") },
+  { name: "factories.utils", loader: () => import("@simpill/factories.utils") },
+  { name: "file.utils", loader: () => import("@simpill/file.utils") },
+  { name: "function.utils", loader: () => import("@simpill/function.utils") },
+  { name: "http.utils", loader: () => import("@simpill/http.utils") },
+  { name: "logger.utils", loader: () => import("@simpill/logger.utils") },
+  { name: "middleware.utils", loader: () => import("@simpill/middleware.utils") },
+  { name: "misc.utils", loader: () => import("@simpill/misc.utils") },
+  { name: "nextjs.utils", loader: () => import("@simpill/nextjs.utils") },
+  { name: "number.utils", loader: () => import("@simpill/number.utils") },
+  { name: "observability.utils", loader: () => import("@simpill/observability.utils") },
+  { name: "protocols.utils", loader: () => import("@simpill/protocols.utils") },
+  { name: "react.utils", loader: () => import("@simpill/react.utils") },
+  { name: "request-context.utils", loader: () => import("@simpill/request-context.utils") },
+  { name: "resilience.utils", loader: () => import("@simpill/resilience.utils") },
+  { name: "socket.utils", loader: () => import("@simpill/socket.utils") },
+  { name: "test.utils", loader: () => import("@simpill/test.utils") },
+  { name: "token-optimizer.utils", loader: () => import("@simpill/token-optimizer.utils") },
+  { name: "zod.utils", loader: () => import("@simpill/zod.utils") },
+  { name: "zustand.utils", loader: () => import("@simpill/zustand.utils") },
+];
+
+describe("@simpill package resolution", () => {
+  for (const { name, loader } of PACKAGES_TO_RESOLVE) {
+    it(`resolves @simpill/${name}`, async () => {
+      const mod = await loader();
+      expect(mod).toBeDefined();
+      expect(mod).not.toBeNull();
+      expect(typeof mod).toBe("object");
+    });
+  }
+});

package/__tests__/unit/@simpill/array.utils/array.utils.unit.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import * as ArrayUtils from "@simpill/array.utils";
+
+describe("@simpill/array.utils", () => {
+  it("resolves and unique returns deduped array", () => {
+    expect(ArrayUtils).toBeDefined();
+    expect(typeof ArrayUtils.unique).toBe("function");
+    const out = ArrayUtils.unique([1, 2, 2, 3, 1]);
+    expect(out).toEqual([1, 2, 3]);
+  });
+});

package/__tests__/unit/@simpill/async.utils/async.utils.unit.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import * as Async from "@simpill/async.utils";
+
+describe("@simpill/async.utils", () => {
+  it("resolves and delay resolves after ms", async () => {
+    expect(Async).toBeDefined();
+    expect(typeof Async.delay).toBe("function");
+    const start = Date.now();
+    await Async.delay(10);
+    expect(Date.now() - start).toBeGreaterThanOrEqual(8);
+  });
+});

package/__tests__/unit/@simpill/cache.utils/cache.utils.unit.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import * as Cache from "@simpill/cache.utils";
+
+describe("@simpill/cache.utils", () => {
+  it("resolves and exports cache utilities", () => {
+    expect(Cache).toBeDefined();
+    expect(typeof Cache).toBe("object");
+    const keys = Object.keys(Cache).filter((k) => (Cache as Record<string, unknown>)[k] != null);
+    expect(keys.length).toBeGreaterThan(0);
+  });
+
+  it("exposes a memoize or createMemoize-like function when present", () => {
+    const C = Cache as Record<string, unknown>;
+    const memoizeFn = C.memoize ?? C.createMemoize;
+    if (typeof memoizeFn !== "function") return;
+    const double = (n: number) => n * 2;
+    const memoized = (memoizeFn as (fn: (n: number) => number) => (n: number) => number)(double);
+    expect(memoized(2)).toBe(4);
+    expect(memoized(2)).toBe(4);
+  });
+});

package/__tests__/unit/@simpill/env.utils/env.utils.unit.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { getEdgeString } from "@simpill/env.utils/client";
+import * as Env from "@simpill/env.utils";
+
+describe("@simpill/env.utils", () => {
+  it("resolves and exports client getEdgeString", () => {
+    expect(Env).toBeDefined();
+    expect(typeof Env).toBe("object");
+    const value = getEdgeString("NODE_ENV", "development");
+    expect(typeof value).toBe("string");
+    expect(value.length).toBeGreaterThanOrEqual(0);
+  });
+});

package/__tests__/unit/@simpill/errors.utils/errors.utils.unit.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import * as Errors from "@simpill/errors.utils";
+
+describe("@simpill/errors.utils", () => {
+  it("resolves and serializeError returns object", () => {
+    expect(Errors).toBeDefined();
+    expect(typeof Errors.serializeError).toBe("function");
+    const out = Errors.serializeError(new Error("test"));
+    expect(out).toBeDefined();
+    expect(typeof out).toBe("object");
+    expect("message" in out || "name" in out).toBe(true);
+  });
+});

package/__tests__/unit/@simpill/object.utils/object.utils.unit.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import * as ObjectUtils from "@simpill/object.utils";
+
+describe("@simpill/object.utils", () => {
+  it("resolves and pick returns subset", () => {
+    expect(ObjectUtils).toBeDefined();
+    expect(typeof ObjectUtils.pick).toBe("function");
+    const out = ObjectUtils.pick({ a: 1, b: 2, c: 3 }, ["a", "c"]);
+    expect(out).toEqual({ a: 1, c: 3 });
+  });
+});

package/__tests__/unit/@simpill/patterns.utils/patterns.utils.unit.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import * as Patterns from "@simpill/patterns.utils";
+
+describe("@simpill/patterns.utils", () => {
+  it("resolves and exports pattern utilities", () => {
+    expect(Patterns).toBeDefined();
+    expect(typeof Patterns).toBe("object");
+    const keys = Object.keys(Patterns).filter((k) => (Patterns as Record<string, unknown>)[k] != null);
+    expect(keys.length).toBeGreaterThan(0);
+  });
+
+  it("pipeAsync composes async steps when present", async () => {
+    const P = Patterns as Record<string, unknown>;
+    const pipeAsync = P.pipeAsync as (...fns: Array<(n: number) => Promise<number>>) => (x: number) => Promise<number>;
+    if (typeof pipeAsync !== "function") return;
+    const addOne = async (n: number) => n + 1;
+    const double = async (n: number) => n * 2;
+    const composed = pipeAsync(addOne, double);
+    const result = await composed(1);
+    expect(typeof result).toBe("number");
+    expect(result).toBe(4);
+  });
+});

package/__tests__/unit/@simpill/string.utils/string.utils.unit.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import * as StringUtils from "@simpill/string.utils";
+
+describe("@simpill/string.utils", () => {
+  it("resolves and exports usable functions", () => {
+    expect(StringUtils).toBeDefined();
+    expect(typeof StringUtils).toBe("object");
+    const keys = Object.keys(StringUtils).filter((k) => typeof (StringUtils as Record<string, unknown>)[k] === "function");
+    expect(keys.length).toBeGreaterThan(0);
+  });
+});

package/__tests__/unit/@simpill/time.utils/time.utils.unit.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import * as Time from "@simpill/time.utils";
+
+describe("@simpill/time.utils", () => {
+  it("resolves and getUnixTimeStamp returns number", () => {
+    expect(Time).toBeDefined();
+    expect(typeof Time.getUnixTimeStamp).toBe("function");
+    const ts = Time.getUnixTimeStamp();
+    expect(typeof ts).toBe("number");
+    expect(ts).toBeGreaterThan(0);
+  });
+});

package/__tests__/unit/@simpill/uuid.utils/uuid.utils.unit.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import * as Uuid from "@simpill/uuid.utils";
+
+describe("@simpill/uuid.utils", () => {
+  it("resolves and generateUUID returns valid uuid string", () => {
+    expect(Uuid).toBeDefined();
+    expect(typeof Uuid.generateUUID).toBe("function");
+    const id = Uuid.generateUUID();
+    expect(typeof id).toBe("string");
+    expect(Uuid.isUUID(id)).toBe(true);
+  });
+});