docs(jsdoc): add examples, typedefs, and fix type expressions for public methods

[michaeljymsgutierrez]

Description

Three improvements to developer experience and documentation quality across the library:

1. README overhaul - fixed inaccuracies accumulated since v2.9.0, improved heading hierarchy, and added a Quick Reference table
2. JSDoc improvements - added @example blocks, typedefs, and clearer descriptions to every public method in the library source
3. Type generation rebuild - rebuilt dist/arm-js-library.js and regenerated types/index.d.ts so the improved JSDoc and @example blocks are visible in VS Code IntelliSense

Github Issue: N/A

Changes

README.md

• Added Quick Reference table listing all 22 public methods after the Overview section
• Fixed heading hierarchy throughout (#### promoted to ###, Collection Records elevated to top-level ##)
• Converted State Properties, Getter/Setter, Request/Retrieve sections from bold bullet lists to proper ### subheadings
• Removed inconsistent --- horizontal rules after headings
• Fixed inaccuracies: destroyRecord HTTP label (GET -> DELETE), groupBy stale "Incorrectly" note removed, id type updated to Number | String, getAlias param name corrected, queryRecord params marked optional
• Added missing demo links for getAlias and getRequestAlias
• Updated TOC to match new structure

packages/src/lib/api-resource-manager.js

• Added @typedef RequestConfig documenting all config options (alias, autoResolve, skip, skipId, ignorePayload, override) - previously undocumented
• Added @typedef CollectionRecord documenting the full runtime record API injected by ARM
• Added @example blocks to all 21 public instance methods and all 24 utility methods (zero examples existed before)
• Added @throws to pushPayload, query, queryRecord, findAll, findRecord
• Updated id param types to {number|string} on findRecord and peekRecord
• Improved descriptions for _saveRecord (UUID-based POST vs PUT logic), pushPayload, setGlobal, setRootScope, getRootScope, and all utility methods
• Fixed stale date in file header
• Fixed invalid JSDoc array type expression {*[]} -> {Array.<*>} in uniq and mapBy method docs (was causing yarn build:jsdocs to fail)

packages/dist/arm-js-library.js + packages/types/index.d.ts

• Rebuilt dist from updated source
• Regenerated types/index.d.ts so @example blocks and updated typedefs appear in VS Code IntelliSense hover cards

Screenshots/Images

N/A - no UI changes.

How Has This Been Tested?

• All 83 unit tests pass (yarn test)
• yarn build:jsdocs passes cleanly after fixing invalid {*[]} type expressions
• Verified @example blocks appear in types/index.d.ts after rebuild
• No functional code changes - documentation and type declarations only

Checklist

• Code follows the project's coding standards and best practices.
• Tests are written for new functionality and existing tests pass.
• Documentation is updated to reflect changes.
• The PR is assigned to the correct reviewers.

Reviewer Guidance

• No logic changes in this PR - purely documentation, JSDoc, and type declaration improvements
• The id - Number | String change in README and JSDoc reflects the v2.9.0 feature that shipped without a docs update
• types/index.d.ts is auto-generated via yarn build:dts - the source of truth is the JSDoc in api-resource-manager.js

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
arm-js-library-demo	Ready	Preview, Comment	Jul 5, 2026 6:33pm