@massif-maps/typings
Problem
docs/api/massif-api.json is turned into TypeScript by a generator that exists twice
(bindings/js/scripts/api-typings, integrations/nativescript/scripts/api-typings). Each copy
writes massif-api.d.ts (types) and schema.ts (runtime tables: property codes, enum names, spec
classes, events), and each consumer commits its own result. Measured on master: the plugin's copy
already lacks SunExposureOptions, computeSunExposure and the Record<string, number> bag types
the SDK side has. A property added to the SDK (TileLayer.farTileLOD, PR #494) is invisible to the
plugin's typings, and its enum names are missing from schema.ts, so resolve.ts cannot translate
FAR_TILE_LOD_DISTANCE and the write falls through to writeByType as a bare setInt.
Target
An app that uses a newer SDK, where the SDK only added or changed properties, bumps
@massif-maps/typings in its own package.json. No plugin release, no plugin code change.
Decisions
1. Contents: types + tables + resolve
schema.ts is runtime data and resolve.ts is the only code that reads it (pure: no native call,
no @nativescript/core). Both ship, so the package is a normal dependency and is not erased at
build time. The surface:
massif-api.d.ts: class names, property paths, specs, methods, events (types only);schema:PROPS,ENUMS,SPEC_CLASS,EVENTS,METHODS,BASES,ALIASES,KIND_OF_CLASS,CLASS_NAMES;resolve:resolvePath,enumName,enumValue,findEvent,propertyNames, ... (moved frombindings/js/src/resolve.ts, which the plugin'sresolve.tsalready duplicates line for line apart from comments).
@massif-maps/api stays a separate package and becomes a consumer: it keeps index.ts,
bridge.ts, observable.ts (the code that talks to a NativeBridge) and re-exports the types
(export type * from '@massif-maps/typings'), so an app's existing imports keep resolving.
Merging them was rejected: a data package that changes on every property addition should not carry
the behaviour that changes on every bridge fix, and vice versa.
2. Versioning
- The typings version is the SDK version,
6.3.0,6.3.0-rc.1: the generator output is a function of the SDK source, so there is nothing else to number it by.release.ymlpublishes it with the other packages, first (npm-packages.pyorder: typings, api, web), one bump each, and@massif-maps/api/@massif-maps/webdepend on exactly that version. - A newer typings than the native SDK describes properties the native side does not have; an older
one hides ones it has. The plugin declares
"@massif-maps/typings": "^6.0.0"independencies(not a peer: a peer makes every app install it by hand and warns on a mismatch instead of resolving it). An app that updates its native SDK also bumps@massif-maps/typingsto the same version; npm dedupes to the app's top-level copy because it satisfies the plugin's range. - Runtime guard (slice 3): a write that comes back
UNKNOWN_PROPERTYfor a path the typings DO know is the mismatch.MassifApiErrorthen says so ("TileLayer.farTileLODis in@massif-maps/typings6.4.0 but the native SDK does not expose it: update the SDK or pin the typings") instead of the bare result code. The typings export their own version for that message.
3. Where it lives, who publishes it
bindings/typings/ in this repo. scripts/gen-api-bindings.sh regenerates it (the generator moves
here from bindings/js/scripts/api-typings, with its typecheck cases); --check already diffs the
committed output, CI runs it. Publishing is the existing trusted-publisher flow
(release workflow): a new
npm package @massif-maps/typings with release.yml as its trusted publisher, no token.
The nested plugin repo deletes src/ui-massifmaps/api/{massif-api.d.ts,schema.ts,resolve.ts} and
scripts/api-typings, keeps only the platform bridges and index.common.ts, and imports from the
package. web/ needs no change: it already imports @massif-maps/api.
4. bindings/typescript/massif.d.ts
Kept as it is. It is a different artefact: verb-level types for a hand-written binding (React
Native, WASM glue), attached to the release as a loose asset, with its own test
(massif.test.ts). It shares no tables with the path-typed API, so folding it in would couple two
consumers for nothing. Revisit if it starts to need the same tables.
5. Working before anything is published
- SDK side:
bindings/jsdepends on"@massif-maps/typings": "file:../typings".npm-packages.pyrewrites that to the release version when it packs. The typings package is built first (npm ci && npm run buildinbindings/typings) whereverbindings/jsis built. - Plugin side: its PR stays draft until the SDK release that carries the package is out, because
the plugin repo builds without this checkout. Until then a developer overrides with
resolutions(portal:../../bindings/typings), uncommitted.
Slices
- SDK repo (first PR):
bindings/typingspackage with a smoke test, generator moved and fixed to read the schema of the repo it runs in (it used to prefer$MASSIF_SDK_HOME, which is the MAIN checkout in a worktree),@massif-maps/apiconsumes it,npm-packages.pyand CI build, test and publish it. Before the first release npm has no@massif-maps/typings: the npmjs.com package (trusted publisherrelease.yml) has to be created by its first publish. - Plugin repo (own branch, draft until slice 1 is released): delete the copies and the
generator, import from the package,
dependenciesentry^<first release>. - Runtime guard: the
UNKNOWN_PROPERTYmessage above. Not in the first PRs. - Later, separate: the plugin's
index.common.tsandbindings/js/src/index.tshave drifted (80 KB and 97 KB); the plugin adopting@massif-maps/apiwith its ownsetBridgeis the end state, and a design of its own.