A TypeScript monorepo of zero-dependency utility libraries and shared configs, used across personal and professional projects. Built to demonstrate industrial-grade practices: strict types, 100% test coverage, automated versioning, and supply-chain security.
| Package | Version | Coverage | Description |
|---|---|---|---|
@gregoiref/result |  |  | Result<T, E> discriminated union — type-safe error handling without exceptions |
@gregoiref/ts-utils |  |  | Advanced TypeScript generics: deepMerge, pick, groupBy, memoize, and more |
@gregoiref/env-validator |  |  | Type-safe environment validation without Zod or dotenv |
@gregoiref/http-client |  |  | Typed fetch wrapper with interceptors, timeout, and Result-based error handling |
@gregoiref/logger |  |  | Structured JSON logger with pluggable transports |
@gregoiref/date |  |  | Date helpers (format, diff, add, clamp) without date-fns or Moment |
@gregoiref/crypto |  | — | Web Crypto API utilities — hashing, HMAC, AES-GCM, PBKDF2, random tokens |
| Package | Description |
|---|---|
@gregoiref/tsconfig | Strict TypeScript configs — base, node, dom, astro, nuxt |
@gregoiref/biome-config | Biome lint + format for TypeScript projects |
@gregoiref/vitest-config | Vitest setup with 100% coverage thresholds |
@gregoiref/commitlint-config | Commitlint config with emoji support |
@gregoiref/cz-config | cz-git config with 12 emoji types |
@gregoiref/changeset-config | Changesets config factory for TypeScript monorepos |
The packages are designed to compose. A typical service layer uses three or four together:
import{createHttpClient}from'@gregoiref/http-client'import{createLogger}from'@gregoiref/logger'import{isOk}from'@gregoiref/result'constlogger=createLogger({level: 'info',context: {service: 'users'}})constclient=createHttpClient({baseUrl: 'https://api.example.com',timeout: 5000})constresult=awaitclient.get<User>('/users/42')if(isOk(result)){logger.info('User fetched',{name: result.value.data.name})}else{logger.error('Fetch failed',{status: result.error.status})}See docs/getting-started.md for five full patterns: HTTP services, env bootstrap, data pipelines, date formatting, and child loggers.
| Alternative | Why this instead |
|---|---|
axios | Wraps fetch with a 5 kB runtime dep; @gregoiref/http-client is a thin typed shell — the only runtime dep is @gregoiref/result from this same monorepo |
zod | Brings 15 kB for runtime validation; @gregoiref/env-validator covers the env-only use case at zero cost |
neverthrow | A fine library — this exists to stay in the monorepo and use no external deps |
date-fns | Comprehensive but heavy; @gregoiref/date covers the 20% of operations that handle 80% of cases |
| Document | Description |
|---|---|
| docs/getting-started.md | Five cross-package usage patterns — HTTP services, env bootstrap, pipelines, dates, child loggers |
| CHANGELOG.md | Cross-package release overview with links to individual changelogs |
| TRACKING.md | Architecture decisions, phase history, and known risks |
| IDEA.md | Package backlog — validated, in-progress, and published status |
Packages are published to GitHub Packages under the @gregoiref scope. Add the registry to your .npmrc:
@gregoiref:registry=https://npm.pkg.github.comThen install any package:
pnpm add @gregoiref/result
pnpm add @gregoiref/ts-utils
pnpm add @gregoiref/http-clientgit clone https://github.com/GregoireF/utils.git
cd utils
pnpm install
# Lint + typecheck + test across all packages
pnpm turbo run check
# Build all packages
pnpm turbo run build
# Run tests with coverage
pnpm turbo run test# Interactive guided commit (Conventional Commits + emoji)
pnpm commit| Tool | Role |
|---|---|
pnpm workspaces | Package manager — hoisted deps, workspace protocol |
| Turborepo | Task orchestration with remote cache and dependsOn graph |
| TypeScript | Strictest compiler flags (exactOptionalPropertyTypes, noUncheckedIndexedAccess) |
| Biome | Unified lint + format — replaces ESLint + Prettier |
| Vitest | Unit tests with v8 coverage, 100% threshold enforced |
| Changesets | Per-package semver versioning + automatic CHANGELOG |
| Dependabot | Automated dependency updates (GitHub Actions + npm) with SHA pinning + auto-merge |
| CodeQL | Static security analysis (security-extended query suite) |
| OSSF Scorecard | Open-source security posture scoring |
| Jazzer.js | Coverage-guided fuzzing — weekly CI + 3 fuzz targets |
| size-limit | Bundle size budget enforced on every PR |
| Dependency Review | Blocks high-severity CVEs and GPL/AGPL deps on PRs |
See CONTRIBUTING.md. Open an issue before writing significant code.
For security vulnerabilities, see SECURITY.md — do not open a public issue.
Canary releases are published daily to GitHub Packages under the
canarydist-tag (1.0.0-canary.<date>.<sha>). Install withpnpm add @gregoiref/result@canary.