# jg-packages

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

Errors, HTTP requests, storage, files, processes, and more, as small packages that share one set of conventions. Each ships its full API reference, so your agent writes less code and you review less of it.

## The packages

**One job each, one set of conventions.** Each one does one job, with the same error handling, naming, and docs as the others. Pick the ones you need; siblings depend on each other only where it saves you code.

### Browsers and Node.js

Typechecked against both runtimes, so they use only the globals both have.

- [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-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.

### Browsers and workers

For pages and service workers, and safe to import during server rendering.

- [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-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-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.

### Node.js

For servers, command-line tools, and build scripts.

- [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-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-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.

## Why agents use them

**Code your agent doesn't have to write.** Agents write code faster than anyone can review it. Each package replaces code an agent would otherwise generate with code that's already tested, documented, and consistent with the rest.

- **Less code to generate and review:** Your agent imports a tested function instead of writing a new one, so there’s less code to generate, review, and maintain.
- **One error model, server to client:** Every failure is an Exception with a stable code and JSON data. APIs send it in one envelope and jg-fetch reads it back, so code checks codes, not messages.
- **Docs inside each package:** Every package ships its full API reference as API.md, and every export has TSDoc, so an agent reads the docs of the installed version from node_modules.
- **Examples that are checked:** Every example in the docs typechecks against the published package, and the ones without I/O run on every release, with their stated results asserted.
- **Tested as you install them:** Each release is packed and installed into a new project before it ships, and browser code is tested in Chromium, Firefox, and WebKit.
- **One set of conventions:** The same names, units in option names, ESM with types, and nothing running at import. An agent that knows one package knows how the others work.

## Set up your agent

**Two steps to put your agent on them.** The policy tells your agent to prefer these packages, and the skill tells it which one fits each task. Both live in jg-skills, so they stay current as the packages change.

1. **Add the policy to your AGENTS.md:** A short `## jg-packages` section that tells your agent to prefer these packages and to check the installed version's `API.md` before using an export. jg-skills keeps it current. [Open the policy](https://github.com/jesusgraterol/jg-skills/blob/main/skills/jg-packages/assets/agents-section.md), and read [about the skill](https://jg-skills.jesusgraterol.dev/skills/jg-packages/).

2. **Install the skill:** It tells your agent which package fits a task, even before the package is installed.

   ```bash
   npx skills add jesusgraterol/jg-skills --skill jg-packages -y
   ```

## Docs for agents

**Docs your coding agent can read.** The same READMEs and API references you read here, as Markdown: inside each package, and on this site.

- `node_modules/<package>/API.md`: The full API reference of the installed version, shipped in every package, so it reads offline.
- `node_modules/<package>/RECIPES.md`: App-side patterns for the package, such as an API exception or a typed client, typechecked on every release.
- [`/llms.txt`](https://jg-packages.jesusgraterol.dev/llms.txt): An index of the packages in the llmstxt.org format, with a link to each package’s Markdown.
- [`/llms-full.txt`](https://jg-packages.jesusgraterol.dev/llms-full.txt): Every package’s README, API reference, and recipes in one file, for loading into a context window.
- `/packages/<name>/index.md`: The Markdown version of each page: a package’s README and its full API reference.
- `Accept: text/markdown`: Request any page with this header to get its Markdown instead of HTML.