tom_som_javascript_v0 — typed TomSpecs object model for JavaScript

> Cross-references. > tom_specs_model/doc/som_multiplatform_spec_model.md > is the SOM authority: SOM §6 decides the split between this > typed access path and the generic one, SOM §8 decides what > this generated surface contains, SOM §4.2 decides the model > version stamp and the editing rules it enforces, and > SOM §17 decides how the package is built and published. > tom_specs_model/doc/index.md catalogues every > TomSpecs subject-matter document and owns the § citation > convention. This README says how to use this package's code; > those documents own the model, the formats and the rules, and > nothing here restates them.

Generated typed TomSpecs object model (v0). An editing facade over the generic tom_som_javascript_runtime; see the meta-data file and DocSpecs schemas in this package. Regenerate with tom_specs_clitool/bin/generate_som.dart.

Where this fits

tom_som_javascript_v0 is the generated typed face of the TomSpecs object model for JavaScript: one type per document section, so a specification is read and written through named members rather than through string paths. It exists because a string path is checked only at run time — a mistyped one reads as an absent value instead of an error — and a specification is exactly the kind of document where that failure is silent and expensive. It is one half of a pair: the hand-written tom_som_javascript_runtime holds everything identical in every language (the sparse document store, the codecs, the validator) and this half holds only what changes when the model changes, so a regeneration rewrites the typed types and touches nothing else. The same pair exists for all nine SOM languages, generated from one model, so a document written through any of them reads identically through the other eight. Plain CommonJS with no build step and no runtime dependencies — require the package and the typed roots are there.

Overview

A TomSpecs document is sparse and path-keyed: a value lives under the globally-unique section-id path it belongs to, and an absent key means "no value" rather than an empty one. This package holds none of those values — SpecDocument, in the runtime, does. What it holds is a typed view: each generated type wraps a document together with the path prefix it is rooted at, and its members resolve to the paths beneath that prefix. Constructing a document root also runs the model-version check (SOM §4.2), so a document stamped by a different model version is refused rather than silently misread.

Everything generated here is derived from the tom_specs_model Dart model and rewritten wholesale on every run of tom_specs_clitool/bin/generate_som.dart. Beside the typed types the package ships the lossless meta-data file (meta/spec_model.meta.json, SOM §5.3), the generated DocSpecs schemas (schemas/, SOM §13), and the metadata trees that drive the dot-notation and id-tree access surfaces (SOM §8). The hand-written trees beside them — examples/, the tests, doc/ — are preserved across regeneration; the generator writes files, it never wipes the output root.

Installation

Install the facade (it depends on tom_som_javascript_runtime):

npm install tom_som_javascript_v0

or pin it in your package.json:

"dependencies": {
  "tom_som_javascript_v0": "^1.3.2"
}

tom_som_javascript_v0 and tom_som_javascript_runtime both carry version 1.3.2, taken from the TomSpecs model version — pin them together. Every other dependency route (git, path, vendored, build-from-source) is in readme_howtointegrate.md.

Features

Document roots

Each root is a whole TomSpecs document, and the first segment of every path beneath it is its section id. Construct the root you need over a SpecDocument; the 1254 model classes are reached through it.

Section id	Document	Generated root type
`SBP`	Solution Blueprint	`D00SolutionBlueprint`
`CLA`	Current Landscape Assessment	`D01CurrentLandscapeAssessment`
`TOM`	Target Operating Model	`D02TargetOperatingModel`
`IFM`	Information Model	`D03InformationModel`
`RSP`	Requirements Specification	`D04RequirementsSpecification`
`ISC`	Interaction Scenarios	`D05InteractionScenarios`
`ATS`	Architecture & Technology Specification	`D06ArchitectureTechnologySpecification`
`IIS`	Integration & Interface Specification	`D07IntegrationInterfaceSpecification`
`SAS`	Security & Access Specification	`D08SecurityAccessSpecification`
`XDS`	Experience Design Specification	`D09ExperienceDesignSpecification`
`QAP`	Quality & Acceptance Plan	`D10QualityAcceptancePlan`
`DRM`	Delivery Roadmap	`D11DeliveryRoadmap`
`TRP`	Transition & Rollout Plan	`D12TransitionRolloutPlan`
`CGP`	CodeSpecs Generation Projection	`D13CodeSpecsProjection`

Quick start

Add tom_som_javascript_v0 to your project (npm install tom_som_javascript_v0), then:

const m = require('tom_som_javascript_v0');
const { SpecDocument } = require('tom_som_javascript_runtime');

// A typed Solution Blueprint over a fresh document.
const doc = new SpecDocument();
const blueprint = new m.D00SolutionBlueprint(doc);

blueprint.content = 'A platform that unifies our fragmented order systems.';
blueprint.currentLandscape.content =
    'Three legacy systems with no shared customer record.';

console.log(blueprint.content);

Prints A platform that unifies our fragmented order systems. — the value just written, read back through the typed getter.

Examples

Sample	Demonstrates
`a_typed_access.js`	The generated typed facade — named members, nested-section navigation, and the typed `SomList` collection.
`b_generic_document.js`	The generic runtime underneath — string paths into a sparse store, plus JSON and YAML serialization.
`c_reflection_metadata.js`	The value-free reflection surface — load `meta/spec_model.meta.json` , enumerate roots and fields, resolve a path to the model node it lands on.

examples/README.md gives the run command for each.

For complete, runnable sample projects — a whole task carried end to end across several packages rather than one package's API — see tom_specs_samples/.

Usage

The generic store underneath

A facade is a view; the document is the value. Reach past the typed types whenever a path is computed rather than known — both sides address exactly the same store.

const m = require('tom_som_javascript_v0');
const { SpecDocument, yamlEncode } = require('tom_som_javascript_runtime');

const doc = new SpecDocument();
doc.setContent(
  'SBP/content', 'A platform that unifies our fragmented order systems.');

// A repeated section: append an item, then fill a content leaf under it.
const item = doc.addListItem('SBP/currentLandscape/CUOPME-OPER-LST');
doc.setContent(`${item}/content`, 'Average order turnaround: 4.2 days.');

// The whole document serializes to the canonical wire format.
console.log(yamlEncode(doc, m.d00SolutionBlueprintMetaTree, '1.0'));

Metadata and reflection

The exported class graph answers "what can the model hold?" with no document values involved — enumerate roots and fields, or resolve a concrete path to the model node it lands on (SOM §7).

const fs = require('fs');
const { SpecModel, SpecReflection } =
  require('tom_som_javascript_runtime');

const model = SpecModel.fromJson(
  JSON.parse(fs.readFileSync('meta/spec_model.meta.json', 'utf8')));
const reflection = new SpecReflection(model);

for (const root of reflection.roots) {
  console.log(reflection.rootSegment(root), root.title);
}

const res = reflection.resolve('SBP/currentLandscape/content');
console.log(`kind=${res.kind}  valueLeaf=${res.isValueLeaf}`);

Regenerating

This package is output. When the model changes, regenerate it rather than editing it — every file carrying the GENERATED … do not edit by hand banner is overwritten:

dart run tom_specs_clitool/bin/generate_som.dart

Architecture

  tom_som_javascript_v0          the typed path — this package
    D00SolutionBlueprint …        one type per document root
            │  extends
            ▼
     SomNode / SomScalar / SomList     editing-facade bases
            │  bound to
            ▼
      SpecDocument                sparse, path-keyed value store
            │                     (tom_som_javascript_runtime)
            ▼
  SpecReflection · SpecValidator · YAML + Markdown codecs
            ▲
            │  described by
      SomMetaTree  ◀── meta/spec_model.meta.json

Type	Responsibility
`D00SolutionBlueprint` …	The generated document roots — one per row of the table above, each the typed entry point to a whole document.
`SomNode`	The base every generated section type extends: a document plus the path prefix this section is rooted at.
`SomScalar`	A typed leaf — parse and format at the store boundary, so `int` / `bool` / enum members read as themselves.
`SomList`	A typed repeated section — append, index and enumerate items whose paths the store generates.
`SomMetaTree` / `SomMetaNode`	The generated metadata trees ( `SOM §7` ): the model's shape as data, behind the dot-notation and id-tree access surfaces.
`SomEditability`	The `SOM §4.2` version-check outcome — whether a stamped document may be edited by this facade.
`SpecDocument`	The value store itself. Lives in `tom_som_javascript_runtime` ; every type above is a view onto it.

Ecosystem

  tom_specs_model          the Dart model — the source of truth
         │
         ▼  generate_som
  tom_specs_clitool        the generator
         │
         ▼  emits
  tom_som_javascript_v0   ← this package (typed)
         │
         ▼  depends on
  tom_som_javascript_runtime  (generic, hand-written)
         │
         ▼  validated against
  tom_som_conformance      the shared cross-language corpus

The same shape repeats for all nine languages; the corpus at the bottom is shared, which is what makes "identical in every language" a measured claim rather than an intention (SOM §19).

Further documentation

TomSpecs subject matter — the authorities this package implements:

Document	Authority for
index.md	The catalogue of every TomSpecs subject-matter document, and the `§` citation convention.
som_multiplatform_spec_model.md	The two access paths, what this generated surface contains, the version stamp and editing rules, the `.md` and `.docspecs.yaml` formats, and the conformance corpus.
som_toolchains.md	This language plane's build and verify toolchain, and the reference host.
tom_specs_model_meta_schema.md	The on-disk schema of `meta/spec_model.meta.json`.

This package — its own guides:

Guide	Covers
doc/tutorial.md	A JavaScript walkthrough end to end — install, open a document, read and edit a section, validate it, and serialize to `*.docspecs.yaml` and Markdown.
readme_howtointegrate.md	Every dependency route, how to pin the version, and building from source.
examples/README.md	The runnable samples and how to run each.

Siblings — packages you will reach for next:

Package	What it is
tom_som_javascript_runtime	The generic runtime this facade is a view over — reach for it directly to drive a document by path.
tom_som_conformance	The shared corpus and the cross-language drivers that run every port against it.
tom_specs_clitool	The generator that writes this package.

Status

Version 1.3.2, tracking the TomSpecs model version and matching tom_som_javascript_runtime. Generated surface: 14 document roots, 1254 model classes. Verify the package with:

npm install
./run_tests.sh   # the per-module suites + the three samples

A generated README states no fixed test count: the count moves with the model, and a number this file could not update would go stale the first time the model did. The command above is the standing answer — it runs this package against the shared cross-language corpus (SOM §19).