# jg-packages

> Small, tested TypeScript packages for coding agents to build on: errors, HTTP requests, storage, files, and processes, with docs inside each one.

Every package ships its full API reference as `API.md` and its recipes as `RECIPES.md`, so an agent can read the installed version from `node_modules`. Every page of this site has a Markdown version at `index.md` in its directory, and returns it when requested with `Accept: text/markdown`.

## Agent setup

- [The jg-packages policy](https://github.com/jesusgraterol/jg-skills/blob/main/skills/jg-packages/assets/agents-section.md): A `## jg-packages` section for a project's AGENTS.md that tells its agent to prefer these packages and to check the installed version's API.md.
- [The jg-packages skill](https://jg-skills.jesusgraterol.dev/skills/jg-packages/): Tells an agent which package fits a task. Install it with `npx skills add jesusgraterol/jg-skills --skill jg-packages -y`.

## Packages

- [jg-exception](https://jg-packages.jesusgraterol.dev/packages/jg-exception/index.md): Coded errors for every jg package: an Exception with a stable code and JSON data, message extraction, code checks, and test assertions.
- [jg-api-response](https://jg-packages.jesusgraterol.dev/packages/jg-api-response/index.md): Build and recognise the success, data, and error envelope that services exchange over HTTP, with errors as a code, a message, and data.
- [jg-utilities](https://jg-packages.jesusgraterol.dev/packages/jg-utilities/index.md): Validations, formatters, secure random generators, pagination cursors, and collection, async, and environment helpers.
- [jg-bignumber](https://jg-packages.jesusgraterol.dev/packages/jg-bignumber/index.md): Exact decimal math on bignumber.js: rounding modes, formatting, and financial calculations such as percentage changes.
- [jg-fetch](https://jg-packages.jesusgraterol.dev/packages/jg-fetch/index.md): A fetch wrapper that never throws: timeouts, retries that honour Retry-After, response size caps, and API envelopes.
- [jg-storage](https://jg-packages.jesusgraterol.dev/packages/jg-storage/index.md): Typed key-value stores over localStorage, sessionStorage, IndexedDB, and memory, for pages and workers alike.
- [jg-sw](https://jg-packages.jesusgraterol.dev/packages/jg-sw/index.md): A generated caching worker with a Vite plugin and CLI, plus registration, updates that reload once, and app installation.
- [jg-fs](https://jg-packages.jesusgraterol.dev/packages/jg-fs/index.md): Filesystem helpers, async and sync: path checks, directories, text and JSON files, atomic writes, and bounded reads.
- [jg-process](https://jg-packages.jesusgraterol.dev/packages/jg-process/index.md): Run and stop child processes without a shell: timeouts, output limits, abort signals, and whole process trees.
- [jg-clipboard](https://jg-packages.jesusgraterol.dev/packages/jg-clipboard/index.md): Copy and read text, HTML, and images on the browser clipboard, with support detection and coded errors that say why the browser refused.
- [jg-env](https://jg-packages.jesusgraterol.dev/packages/jg-env/index.md): Strict environment variable readers for process.env or import.meta.env, plus secret files, with errors that name the key and never the value.
- [jg-postgres](https://jg-packages.jesusgraterol.dev/packages/jg-postgres/index.md): node-postgres helpers: transactions that report an unknown commit, advisory locks, SQLSTATE checks, cursor pages, and ordered lists.
- [jg-redis](https://jg-packages.jesusgraterol.dev/packages/jg-redis/index.md): A read-through cache that keeps working when Redis fails, and fail-closed one-time claims and single-use values, on node-redis.
- [jg-react](https://jg-packages.jesusgraterol.dev/packages/jg-react/index.md): React hooks for online status, page visibility, Tailwind CSS breakpoints, and scroll thresholds, each safe in a server render.
- [jg-tanstack-query](https://jg-packages.jesusgraterol.dev/packages/jg-tanstack-query/index.md): TanStack Query with safe defaults, opt-in IndexedDB persistence, and a sign-out clear that waits for the cache to finish restoring.
- [jg-react-router](https://jg-packages.jesusgraterol.dev/packages/jg-react-router/index.md): React Router helpers: a page outlet that focuses each new page and restores scroll on Back and Forward, and dialogs that close when the route changes.
- [jg-nestjs](https://jg-packages.jesusgraterol.dev/packages/jg-nestjs/index.md): NestJS for HTTP APIs: an ApiException, a filter and an interceptor for the jg-api-response envelope, schema validation, CORS, and app bootstrap.
- [jg-crypto](https://jg-packages.jesusgraterol.dev/packages/jg-crypto/index.md): Hashing, random bytes and digits, and HMAC signatures with constant-time verification, for Node.js.

## Recipes

- [jg-exception recipes](https://jg-packages.jesusgraterol.dev/packages/jg-exception/recipes/index.md): Patterns for apps that throw coded errors, report them, show them to users, keep secrets out of them, and handle them by their code.
- [jg-api-response recipes](https://jg-packages.jesusgraterol.dev/packages/jg-api-response/recipes/index.md): Patterns for APIs that answer every error with a status and an envelope, and for code that reads another service's envelope.
- [jg-utilities recipes](https://jg-packages.jesusgraterol.dev/packages/jg-utilities/recipes/index.md): Patterns for apps that page through lists, cache results by request, check what clients send, and share a rate-limited API, with jg-utilities' cursor codecs, JSON helpers, validations, and request coordinator.
- [jg-bignumber recipes](https://jg-packages.jesusgraterol.dev/packages/jg-bignumber/recipes/index.md): Patterns for apps that add up money and report how a metric changed, with exact decimal math and rounding where you choose.
- [jg-fetch recipes](https://jg-packages.jesusgraterol.dev/packages/jg-fetch/recipes/index.md): Patterns for apps that call HTTP APIs with jg-fetch: a typed client for an envelope API, auth headers that stay fresh, and retries that never repeat an unsafe request.
- [jg-storage recipes](https://jg-packages.jesusgraterol.dev/packages/jg-storage/recipes/index.md): Patterns for apps that keep settings and drafts in the browser, and keep working where the browser blocks storage.
- [jg-sw recipes](https://jg-packages.jesusgraterol.dev/packages/jg-sw/recipes/index.md): Patterns for Vite apps that keep working offline, and tell people when a new version is ready.
- [jg-fs recipes](https://jg-packages.jesusgraterol.dev/packages/jg-fs/recipes/index.md): Patterns for Node.js apps that keep their files whole through crashes, and read files from users within a size limit.
- [jg-process recipes](https://jg-packages.jesusgraterol.dev/packages/jg-process/recipes/index.md): Patterns for Node.js scripts that run CLIs within a time and output budget, start servers and wait until they answer, and run package scripts on any platform.
- [jg-clipboard recipes](https://jg-packages.jesusgraterol.dev/packages/jg-clipboard/recipes/index.md): Patterns for copy and paste buttons that work across browsers, and say what to do when the browser refuses.
- [jg-env recipes](https://jg-packages.jesusgraterol.dev/packages/jg-env/recipes/index.md): Patterns for reading a program's configuration once, at startup, from the environment and from secret files.
- [jg-postgres recipes](https://jg-packages.jesusgraterol.dev/packages/jg-postgres/recipes/index.md): Patterns for PostgreSQL services: wiring pools, turning constraint errors into app errors, paginating, timeouts for slow work, and verification codes.
- [jg-redis recipes](https://jg-packages.jesusgraterol.dev/packages/jg-redis/recipes/index.md): Patterns for services that use Redis: wiring the client into an app, caching a slow query, stopping a one-time code's replay, and keeping an IP blocklist.
- [jg-react recipes](https://jg-packages.jesusgraterol.dev/packages/jg-react/recipes/index.md): Patterns for components that follow the browser: the network, the tab, the viewport, the theme, copying to the clipboard, and uploading files.
- [jg-tanstack-query recipes](https://jg-packages.jesusgraterol.dev/packages/jg-tanstack-query/recipes/index.md): Patterns for React apps that cache server data with TanStack Query: setting it up, keeping a query across reloads, signing out safely, and a query boundary.
- [jg-react-router recipes](https://jg-packages.jesusgraterol.dev/packages/jg-react-router/recipes/index.md): Layouts that restore scroll on Back and Forward, dialogs that close when the user navigates away, and titles from a route map, in React Router apps.
- [jg-nestjs recipes](https://jg-packages.jesusgraterol.dev/packages/jg-nestjs/recipes/index.md): Wiring the envelope, validation, and error reporting into a NestJS API, starting it, reporting failures, and adding maintenance mode or an IP blocklist.
- [jg-crypto recipes](https://jg-packages.jesusgraterol.dev/packages/jg-crypto/recipes/index.md): Patterns for Node.js services that verify webhooks, keep tokens out of their database, and sign the values they hand to clients.