Function metadata API: getAvailableFunctions / getFunctionDetails (HF-249)

[marcin-kordas-hoc]

Summary

Adds a two-tier public API for retrieving built-in function metadata, intended for a Formula Builder / function picker:

• HyperFormula.getAvailableFunctions(code) (static) / hfInstance.getAvailableFunctions() (instance) → FunctionListEntry[] — a short, sorted list: translated name, canonical name, category, short description.
• HyperFormula.getFunctionDetails(canonicalName, code) (static) / hfInstance.getFunctionDetails(canonicalName) (instance) → FunctionDetails | undefined — full details including generated syntax and per-parameter optionality/repeatability.

Instance methods delegate to the static ones using the configured language. The catalogue covers built-in functions only — custom functions are not listed and getFunctionDetails returns undefined for them.

Catalogue

The 363-function catalogue is generated from docs/guide/built-in-functions.md by scripts/hf249-migrate-function-docs.ts (dev-only; not shipped — tsconfig include is ["src"]). Parameter names come from the Syntax column; their count and optionality follow the implementation arity in implementedFunctions. Repeating groups collapse onto the arity and duplicate names are disambiguated.

Tests

Paired tests PR: handsontable/hyperformula-tests#14 (branch feature/hf-249-function-metadata-api):

• public API: static + instance, i18n, custom-function exclusion, present-but-empty MVP fields
• coverage parity: FUNCTION_DOCS keys == canonical set (both directions)
• parameter consistency: count == arity, unique non-empty names, repeatable count == repeatLastArgs
• generated-syntax fixtures, ordering determinism, 18-language i18n sweep, normalized migration fidelity vs the docs

MVP scope

parameters[].description, documentationUrl, and examples are present but empty; authored in a later phase.

Notes

• Sort order: category, then canonical name.
• Empty language-pack translations fall back to the canonical id (e.g. SWITCH in several locales).

---

Note

Medium Risk
Large additive public API and generated catalogue; runtime behavior is read-only metadata, but list/detail consistency depends on doc vs implementation arity staying in sync.

Overview
Adds a two-tier public API for built-in function metadata (formula pickers / builders): getAvailableFunctions() returns a sorted short list (translated name, canonical id, category, description), and getFunctionDetails(canonicalName) returns full details including generated syntax and per-parameter optional/repeatable flags. Both exist as static methods (with language code) and instance helpers (instance language).

Introduces a FUNCTION_DOCS catalogue (~363 functions) under src/interpreter/functionMetadata/, composed from per-category files and regenerated from docs/guide/built-in-functions.md via dev-only scripts/hf249-migrate-function-docs.ts. Listing is gated so only documented, registered functions with catalogue arity matching implementedFunctions appear—custom functions are excluded (getFunctionDetails → undefined).

Exports new types (FunctionListEntry, FunctionDetails, etc.) from the package entry. MVP leaves parameters[].description, documentationUrl, and examples empty for a later phase.

^{Reviewed by Cursor Bugbot for commit c98e9b1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Performance comparison of head (c98e9b1) vs base (d4195b5)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A |  481.1 | 482.18 | +0.22%
                                      Sheet B | 152.91 | 153.06 | +0.10%
                                      Sheet T | 136.15 | 134.95 | -0.88%
                                Column ranges | 506.02 | 507.82 | +0.36%
Sheet A:  change value, add/remove row/column |  14.72 |  15.64 | +6.25%
 Sheet B: change value, add/remove row/column | 131.15 | 131.82 | +0.51%
                   Column ranges - add column | 150.47 |  156.2 | +3.81%
                Column ranges - without batch | 469.01 | 469.07 | +0.01%
                        Column ranges - batch | 119.76 | 119.29 | -0.39%

[netlify]

✅ Deploy Preview for hyperformula-dev-docs ready!

Name	Link
🔨 Latest commit	c98e9b1
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a294ec37b316200089716ac
😎 Deploy Preview	https://deploy-preview-1692--hyperformula-dev-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4078a56. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.17%. Comparing base (d4195b5) to head (c98e9b1).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1692      +/-   ##
===========================================
+ Coverage    97.16%   97.17%   +0.01%     
===========================================
  Files          176      192      +16     
  Lines        15322    15412      +90     
  Branches      3356     3401      +45     
===========================================
+ Hits         14887    14977      +90     
- Misses         427      435       +8     
+ Partials         8        0       -8     

Files with missing lines	Coverage Δ
src/HyperFormula.ts	99.74% <100.00%> (+0.01%)	⬆️
src/index.ts	100.00% <ø> (ø)
...nterpreter/functionMetadata/FunctionDescription.ts	100.00% <100.00%> (ø)
...eter/functionMetadata/buildFunctionDescriptions.ts	100.00% <100.00%> (ø)
.../functionMetadata/categories/array-manipulation.ts	100.00% <100.00%> (ø)
...nterpreter/functionMetadata/categories/database.ts	100.00% <100.00%> (ø)
...reter/functionMetadata/categories/date-and-time.ts	100.00% <100.00%> (ø)
...rpreter/functionMetadata/categories/engineering.ts	100.00% <100.00%> (ø)
...terpreter/functionMetadata/categories/financial.ts	100.00% <100.00%> (ø)
...rpreter/functionMetadata/categories/information.ts	100.00% <100.00%> (ø)
... and 8 more

... and 5 files with indirect coverage changes

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