docs(net): expand @cacheable/net README with full API, Features, and Table of Contents

[jaredwray]

Summary

Makes the @cacheable/net README much more robust, mirroring the structure of the cacheable package README. It now documents the full public API surface with a complete, working Table of Contents.

What changed

• Expanded Features list covering fetch semantics, method helpers, layered caching, RFC 7234, simple caching, coalescing, serialization, WHOIS/RDAP, Hookified, and typing.
• Full Table of Contents with anchors verified to resolve to real headings.
• HTTP usage docs: method helpers (get/post/put/patch/delete/head) with a signature/return/caching table, the DataResponse shape, fetch usage, caching control, RFC 7234 HTTP cache semantics, simple caching mode, custom serialization (stringify/parse), and error handling.
• Custom/shared cache section (construct from options or share a Layer 1/Layer 2 Cacheable), plus an Events section via the underlying cache.
• Standalone functions documented (fetch, get, post, patch, del, head) — including the note that there is no standalone put and why del is named del.
• WHOIS & RDAP reference: full WhoisOptions / RdapOptions / QueryWhoisServerOptions tables, WhoisResult / WhoisHop / WhoisFields / RdapResult type shapes, referral following, and the exported parsing helpers (normalizeWhoisQuery, detectQueryType, parseWhois, queryWhoisServer).
• Reference sections: CacheableNet options table, full API (properties + methods), and a complete exports/types list.

Notes

• Documentation only — no source or behavior changes.
• API claims (signatures, options, defaults, type shapes, exported symbols), code examples, and every ToC anchor were cross-checked against packages/net/src.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ERPCDjhDCjXjwrAkBD9z3Y

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request extensively updates and expands the README.md documentation for @cacheable/net. It adds detailed sections covering basic usage, HTTP method helpers, response handling, caching control, custom serialization, error handling, custom/shared caches, events, standalone functions, WHOIS/RDAP lookups, options, and API references. There are no review comments to evaluate, and I have no additional feedback to provide on these documentation updates.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (35c90d9) to head (ba7ca4c).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1666   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           29        29           
  Lines         3504      3504           
  Branches       794       795    +1     
=========================================
  Hits          3504      3504           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 00815fc960

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jaredwray]

Thanks for the reviews. All three Codex points are addressed in 82a8ba5 (kept docs-only, since this PR is scoped to the README):

• Write-method caching — corrected to state that only GET (by default) and PUT (caching: true) are cached. fetch.ts:128-136 skips the cache for POST/PATCH/DELETE/HEAD, so those are now documented as never cached, with a note that the caching option has no effect on them.
• PUT cache identity — the note now says the cache key is method + URL only (fetch.ts:142); the request body is not part of it.
• Request coalescing — scoped to simple caching mode (httpCachePolicy: false) and WHOIS/RDAP lookups; the default RFC 7234 path does not coalesce.
• Also clarified that the standalone get/post/patch/head helpers require an options argument and del requires an options object (they throw otherwise).

Note: the POST/PATCH/DELETE caching no-op (the caching: true option being silently ignored for those methods) looks like a latent bug in fetch.ts rather than intended behavior — flagging it here in case it's worth a separate code fix + tests that assert an actual cache hit.

---

Generated by Claude Code