You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
API consistency findings surfaced by TS contract tests #1202
The new API contract tests added in #1018 (branch @ms/api-tests-scaffold) surfaced several inconsistencies across the public TypeScript surface. They are currently encoded as explicit exception sets in the test files so the suite passes today; this issue tracks the cleanup work.
Modules that don't extend BaseModule
BaseModule provides the shared delete() / forwardET() / getInputShape() plumbing and the generateFromFrame JSI binding hook. The following modules skip it and re-implement (or omit) parts of that contract:
OCRModule
VerticalOCRModule
LLMModule
SpeechToTextModule
TextToSpeechModule
TokenizerModule
Listed in SKIPS_BASE_MODULE in __tests__/api/moduleContracts.test.ts.
Modules without a static from* factory
Every other module uses Module.fromModelName(...) / Module.fromCustomModel(...) as the construction entry point:
ExecutorchModule — constructs blank and exposes an instance load() method instead.
TokenizerModule — no factory at all.
Listed in SKIPS_STATIC_FACTORY.
Hook naming inconsistency
Every hook drops the Module suffix from its module class name (ClassificationModule → useClassification, LLMModule → useLLM) except:
ExecutorchModule → useExecutorchModule (keeps the suffix).
Listed in HOOK_NAME_EXCEPTIONS.
Informational: parameterized registry accessor
models.ocr.craft({ language }) requires a language argument, while every other accessor in the registry is either fully parameterless or takes only optional ModelOpts. This is intentional (OCR pipelines are picked per language), but worth flagging because the test walker has to special-case it. Listed in PARAMETERIZED_ACCESSORS in __tests__/api/modelRegistry.test.ts.
How to act on this
Each bullet above corresponds to an entry in one of the exception sets. As an inconsistency is fixed at the source, the matching entry can be deleted and the contract test will start enforcing the rule for that module.
Every other public useXxx hook takes a single object argument, e.g.:
useClassification({ model, preventLoad });
useTextToSpeech is the lone outlier:
useTextToSpeech(model,{ preventLoad });
Tracked in __tests__/api/hookPropsContract.test.ts as a documented opt-out (useTextToSpeech is excluded from the single-arg contract assertion). Normalising the signature to useTextToSpeech({ model, preventLoad }) would be a breaking change but would let the contract test enforce the rule across the whole hook surface.
TokenizerModule has no delete() method
BaseModule.delete() calls this.nativeModule.unload() to release native resources. TokenizerModule doesn't extend BaseModule (already noted in the original list) and doesn't declare its own delete(), so the native tokenizer handle allocated in load() is never released — a latent memory leak per loaded tokenizer.
Tracked in __tests__/api/modulePrototype.test.ts via SKIPS_DELETE (TokenizerModule is the sole entry). Adding a delete() that unloads this.nativeModule is the minimal fix.
Two more inconsistencies surfaced while writing moduleConstruction.test.ts and moduleHookSignatureAlignment.test.ts:
TextToImageModule.forward is exposed as useTextToImage().generate
The module's primary inference method is forward(input, imageSize?, numSteps?, seed?) and the hook return advertises it as generate(...) with the same signature. Every other module that has both a forward on the prototype and a forward field on the hook return uses the same name; TTI is the outlier.
moduleHookSignatureAlignment.test.ts documents the rename as textToImage_forward_to_generate so the signatures still get cross-checked.
VisionModule.runOnFrame is a throwing getter
Not a public-API bug, but worth flagging for anyone introspecting the module surface (e.g. doc generators, IDE tooling): accessing VisionModule.prototype.runOnFrame without a loaded nativeModule throws RnExecutorchError(ModuleNotLoaded). modulePrototype.test.ts works around this by using Object.getOwnPropertyDescriptor instead of direct property access.
Activity
test: add hook return contract + model URL validation tests
test: add error code, TTS voice, and API surface contract tests
msluszniak commentedon May 29, 2026
Update: deeper tests on branch
@ms/api-tests-scaffoldsurface two more inconsistencies:useTextToSpeechtakes two positional argsEvery other public
useXxxhook takes a single object argument, e.g.:useTextToSpeechis the lone outlier:Tracked in
__tests__/api/hookPropsContract.test.tsas a documented opt-out (useTextToSpeechis excluded from the single-arg contract assertion). Normalising the signature touseTextToSpeech({ model, preventLoad })would be a breaking change but would let the contract test enforce the rule across the whole hook surface.TokenizerModulehas nodelete()methodBaseModule.delete()callsthis.nativeModule.unload()to release native resources.TokenizerModuledoesn't extendBaseModule(already noted in the original list) and doesn't declare its owndelete(), so the native tokenizer handle allocated inload()is never released — a latent memory leak per loaded tokenizer.Tracked in
__tests__/api/modulePrototype.test.tsviaSKIPS_DELETE(TokenizerModuleis the sole entry). Adding adelete()that unloadsthis.nativeModuleis the minimal fix.test: add hook props, registry compatibility, and prototype surface t…
msluszniak commentedon May 29, 2026
Two more inconsistencies surfaced while writing
moduleConstruction.test.tsandmoduleHookSignatureAlignment.test.ts:TextToImageModule.forwardis exposed asuseTextToImage().generateThe module's primary inference method is
forward(input, imageSize?, numSteps?, seed?)and the hook return advertises it asgenerate(...)with the same signature. Every other module that has both aforwardon the prototype and aforwardfield on the hook return uses the same name; TTI is the outlier.moduleHookSignatureAlignment.test.tsdocuments the rename astextToImage_forward_to_generateso the signatures still get cross-checked.VisionModule.runOnFrameis a throwing getterNot a public-API bug, but worth flagging for anyone introspecting the module surface (e.g. doc generators, IDE tooling): accessing
VisionModule.prototype.runOnFramewithout a loadednativeModulethrowsRnExecutorchError(ModuleNotLoaded).modulePrototype.test.tsworks around this by usingObject.getOwnPropertyDescriptorinstead of direct property access.test: add module construction, signature alignment, and CI wiring
msluszniak commentedon Aug 12, 2026
This issue is stale as we reconstructed an API on
rne-rewrite.