@typemf/generator 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typemf/generator",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
@@ -30,9 +30,9 @@
     "provenance": true
   },
   "dependencies": {
-    "@typemf/core": "0.6.0",
-    "@typemf/node": "0.6.0",
-    "@typemf/xmi": "0.6.0",
+    "@typemf/core": "0.8.0",
+    "@typemf/node": "0.8.0",
+    "@typemf/xmi": "0.8.0",
     "nunjucks": "^3.2.4",
     "prettier": "^3.9.8"
   },

package/templates/typescript/eclass.njk

@@ -43,7 +43,7 @@ export interface {{ eClass.getName() }} extends {{ superClass.getName() if super
 {% else %}
 {% set _ = useImport("EObjectImpl", "impl", {foundational: true}) %}
 {% endif %}
-{% set _ = useImport("BasicEList", "impl", {foundational: true}) %}
+{% if options['generate-ecore'] or hasStoredManyValuedFeature(ownFeatures) %}{% set _ = useImport("BasicEList", "impl", {foundational: true}) %}{% endif %}
 {% for feature in ownFeatures %}
 {% if feature.isMany() %}
 {% set _ = useImport("EList", "types", {foundational: true}) %}
@@ -115,72 +115,54 @@ export class {{ eClass.getName() }}Impl extends {{ (superClass.getName() + "Impl
 {% endif %}
 {% endfor %}
 
-{% if eClass.getName() == "EClassifier" %}
-  {#- classifierID is real, internal dispatch bookkeeping (matching
-      @typemf/core's own hand-written EClassifierImpl), not a modeled
-      Ecore feature - so it's declared here, once, on EClassifier itself
-      (inherited by every descendant: EClass, EDataType, EEnum, ...)
-      rather than emitted by the ordinary feature-driven generation
-      above, which has no feature to generate it from. Confirmed
-      necessary by actually running self-hosted bootstrap code (which
-      constructs real EClassifier-derived metaclass shells and needs to
-      set their classifierID), not assumed - see NOTES.md. #}
+{% if options['generate-ecore'] and eClass.getName() == "EClassifier" %}
+  {#- Ecore only: the classifier ID is bookkeeping, not a modeled feature, inherited by every
+      classifier. #}
   private classifierId = -1;
 
   getClassifierID(): number {
     return this.classifierId;
   }
 
+  /** Sets the classifier's ID; called by generated packages. */
   setClassifierID(id: number): void {
     this.classifierId = id;
   }
 {% endif %}
-{% if eClass.getName() == "EStructuralFeature" %}
-  {#- featureID: the exact same real gap as classifierID above, one level
-      down the hierarchy - internal dispatch bookkeeping (matching
-      @typemf/core's own hand-written EStructuralFeatureImpl), not a
-      modeled Ecore feature, declared once here on EStructuralFeature
-      itself (inherited by EAttribute, EReference, ...). Found the same
-      way: running self-hosted bootstrap code, which constructs real
-      EStructuralFeature-derived metaclass shells (EAttributeImpl,
-      EReferenceImpl) and needs to set their featureID - see NOTES.md. #}
+{% if options['generate-ecore'] and eClass.getName() == "EStructuralFeature" %}
+  {#- Ecore only: the feature ID (bookkeeping) and the container class (getter modeled as an
+      operation, setter only on the implementation, used during bootstrap). #}
   private featureId = -1;
 
   getFeatureID(): number {
     return this.featureId;
   }
 
+  /** Sets the feature's ID; called by generated packages. */
   setFeatureID(id: number): void {
     this.featureId = id;
   }
-  {#- containerClass: real EMF's own asymmetric design (see EStructuralFeature.getContainerClass()'s
-      doc comment in @typemf/core) - PUBLIC getter (a real, modeled, reflectively-callable operation),
-      IMPL-ONLY setter (never on the interface, set once during bootstrap - see epackage.njk). Not
-      internal bookkeeping like featureID (it IS a real declared operation), but shares the same
-      "special-cased field the normal per-operation loop must skip" shape, so isBookkeepingOperation
-      treats it the same way (see typescript-filters.ts). #}
+
   private containerClass: {{ useImport("TypeScriptClass", "types", {foundational: true}) }}<unknown> | undefined;
 
   getContainerClass(): {{ useImport("TypeScriptClass", "types", {foundational: true}) }}<unknown> | undefined {
     return this.containerClass;
   }
 
+  /** Sets the implementation class of the declaring class; called by generated packages. */
   setContainerClass(cls: {{ useImport("TypeScriptClass", "types", {foundational: true}) }}<unknown> | undefined): void {
     this.containerClass = cls;
   }
 {% endif %}
-{% if eClass.getName() == "EOperation" %}
-  {#- operationID: the exact same real gap as classifierID/featureID above - internal dispatch
-      bookkeeping (matching @typemf/core's own hand-written EOperationImpl), not a modeled Ecore
-      feature, declared once here on EOperation itself. Same discovery path: self-hosted bootstrap
-      code constructs real EOperationImpl instances and needs to set their operationID - see NOTES.md
-      (point 4). #}
+{% if options['generate-ecore'] and eClass.getName() == "EOperation" %}
+  {#- Ecore only: the operation ID is bookkeeping, not a modeled feature. #}
   private operationId = -1;
 
   getOperationID(): number {
     return this.operationId;
   }
 
+  /** Sets the operation's ID; called by generated packages. */
   setOperationID(id: number): void {
     this.operationId = id;
   }
@@ -196,11 +178,12 @@ export class {{ eClass.getName() }}Impl extends {{ (superClass.getName() + "Impl
 {% if feature.isMany() %}
 {% if getter %}
 {% set _featureImports = registerBodyImports(feature) %}
+  {#- Computed: the cached list is read-only, since changing it would never reach the model. #}
   get{{ ucfirst(feature.getName()) }}(): EList<{{ tsScalarType(feature) }}> {
     if (this._{{ feature.getName() }}CacheGeneration !== EObjectImpl.getModelGeneration()) {
-      this._{{ feature.getName() }}Cache = (() => {
+      this._{{ feature.getName() }}Cache = new {{ useImport("UnmodifiableEList", "impl", {foundational: true}) }}((() => {
         {{ getter | indent(8) }}
-      })();
+      })());
       this._{{ feature.getName() }}CacheGeneration = EObjectImpl.getModelGeneration();
     }
     return this._{{ feature.getName() }}Cache!;
@@ -339,6 +322,7 @@ export class {{ eClass.getName() }}Impl extends {{ (superClass.getName() + "Impl
 {% endfor %}
 
   eGet(feature: EStructuralFeature): unknown {
+    this.requireOwnFeature(feature);
     switch (feature.getFeatureID()) {
 {% for feature in ownFeatures %}
 {% if featureGetter(feature) or trivialDerivedFormula(feature) %}
@@ -363,6 +347,7 @@ export class {{ eClass.getName() }}Impl extends {{ (superClass.getName() + "Impl
   }
 
   eSet(feature: EStructuralFeature, value: unknown): void {
+    this.requireOwnFeature(feature);
     switch (feature.getFeatureID()) {
 {% for feature in ownFeatures %}
 {% if feature.isMany() %}
@@ -445,18 +430,9 @@ export class {{ eClass.getName() }}Impl extends {{ (superClass.getName() + "Impl
     }
   }
 
-  {#- The many-valued analog of eBasicSetValue, for the identical reason:
-      bootstrap code needs to add to a list (eStructuralFeatures,
-      eAnnotations, eSuperTypes, ...) before the feature's own metaclass
-      exists to back the ordinary getter's lazy construction. Constructs
-      the cache with no feature reference when called this way - a real,
-      narrow, deliberate limitation: containment/opposite maintenance on
-      a list built this way is unavailable, since there's no feature to
-      derive it from. Acceptable specifically because only the metamodel's
-      own self-describing bootstrap instances (EClassImpl, EAttributeImpl,
-      etc., as constructed by {Pkg}PackageImpl) ever take this path -
-      ordinary domain instances always go through the normal, fully-
-      wired getter instead, never this one. #}
+{% if options['generate-ecore'] %}
+  {#- Ecore only: the bootstrap adds to lists before the metaclasses their getters need exist. #}
+  /** @internal The list of the many-valued feature `featureId`, for bootstrapping the package. */
   eBootstrapList(featureId: number): BasicEList<unknown> {
     switch (featureId) {
 {% for feature in ownFeatures %}
@@ -474,8 +450,10 @@ export class {{ eClass.getName() }}Impl extends {{ (superClass.getName() + "Impl
 {% endif %}
     }
   }
+{% endif %}
 
   eIsSet(feature: EStructuralFeature): boolean {
+    this.requireOwnFeature(feature);
     switch (feature.getFeatureID()) {
 {% for feature in ownFeatures %}
 {% if feature.isMany() %}
@@ -526,6 +504,7 @@ export class {{ eClass.getName() }}Impl extends {{ (superClass.getName() + "Impl
   }
 
   eUnset(feature: EStructuralFeature): void {
+    this.requireOwnFeature(feature);
     switch (feature.getFeatureID()) {
 {% for feature in ownFeatures %}
 {% if feature.isMany() and not featureGetter(feature) %}

package/templates/typescript/efactory.njk

@@ -1,4 +1,5 @@
 {% set eFactoryClassifier = findEClassByName(package, "EFactory") %}
+{% set pkgClass = packageClassName(package) %}
 {% file factoryClassName(package) + ".ts" %}
 export interface {{ factoryClassName(package) }} extends {{ useImport("EFactory", "types", {foundational: true}) }} {
 {% for classifier in concreteEClassesOf(package) %}
@@ -25,6 +26,14 @@ export interface {{ factoryClassName(package) }} extends {{ useImport("EFactory"
   double-import the old, pre-refactor version of this template had to
   guard against explicitly. #}
 export class {{ factoryClassName(package) }}Impl extends {{ useImport("EFactoryImpl", "impl", {foundational: true}) }} implements {{ useImport(factoryClassName(package), "root", {foundational: false}) }} {
+  /**
+   * The factory instance, as EMF's `{{ factoryClassName(package) }}.eINSTANCE` (on the class, since
+   * TypeScript interfaces have no statics). Reading it constructs the package if necessary.
+   */
+  static get eINSTANCE(): {{ factoryClassName(package) }} {
+    return {{ useImport("get" + pkgClass + "Ref", "impl", {file: pkgClass + "Ref", foundational: false}) }}().getEFactoryInstance() as {{ factoryClassName(package) }};
+  }
+
 {% for classifier in concreteEClassesOf(package) %}
   create{{ classifier.getName() }}(): {{ useImport(classifier.getName(), "types", {foundational: false}) }} {
     return new {{ useImport(classifier.getName() + "Impl", "impl", {foundational: false}) }}();

package/templates/typescript/epackage.njk

@@ -4,13 +4,7 @@
 {% set _ = useImport(name, "types", {foundational: true}) %}
 {% endfor %}
 
-/**
- * Classifier/feature IDs, as pure numeric literals - safe to import from
- * anywhere (Factory, Switch) with zero risk of the circular-import hazard
- * that made a lazy, explicit init() necessary for the singleton itself
- * (see {{ pkgClass }}Impl.ts) - these are just numbers, never require
- * constructing anything.
- */
+/** The classifier, feature and operation IDs; plain numbers, safe to import from anywhere. */
 export const Ids = {
 {% for classifier in package.getEClassifiers() %}
   {{ classifier.getName() }}: { self: {{ classifier.getClassifierID() }}{% if isEClass(classifier) %}{% for feature in classifier.getEStructuralFeatures() %}, {{ feature.getName() }}: {{ feature.getFeatureID() }}{% endfor %}{% for op in classifier.getEOperations() %}, op{{ loop.index0 }}: {{ op.getOperationID() }}{% endfor %}{% endif %} },
@@ -60,27 +54,27 @@ export interface {{ pkgClass }} extends {{ useImport("EPackage", "types", {found
 {% set needsEnum = false %}
 {% set needsEnumLiteral = false %}
 {% set needsAnnotation = false %}
-{% if package.getEAnnotations().size() > 0 %}{% set needsAnnotation = true %}{% endif %}
+{% if runtimeAnnotations(package).length > 0 %}{% set needsAnnotation = true %}{% endif %}
 {% for classifier in package.getEClassifiers() %}
-{% if classifier.getEAnnotations().size() > 0 %}{% set needsAnnotation = true %}{% endif %}
+{% if runtimeAnnotations(classifier).length > 0 %}{% set needsAnnotation = true %}{% endif %}
 {% if isEClass(classifier) %}
 {% for feature in classifier.getEStructuralFeatures() %}
 {% if isEReference(feature) %}{% set needsReference = true %}{% else %}{% set needsAttribute = true %}{% endif %}
-{% if feature.getEAnnotations().size() > 0 %}{% set needsAnnotation = true %}{% endif %}
+{% if runtimeAnnotations(feature).length > 0 %}{% set needsAnnotation = true %}{% endif %}
 {% endfor %}
 {% for op in classifier.getEOperations() %}
 {% set needsOperation = true %}
-{% if op.getEAnnotations().size() > 0 %}{% set needsAnnotation = true %}{% endif %}
+{% if runtimeAnnotations(op).length > 0 %}{% set needsAnnotation = true %}{% endif %}
 {% if op.getEParameters().size() > 0 %}{% set needsParameter = true %}{% endif %}
 {% for param in op.getEParameters() %}
-{% if param.getEAnnotations().size() > 0 %}{% set needsAnnotation = true %}{% endif %}
+{% if runtimeAnnotations(param).length > 0 %}{% set needsAnnotation = true %}{% endif %}
 {% endfor %}
 {% endfor %}
 {% elif isEEnum(classifier) %}
 {% set needsEnum = true %}
 {% for literal in classifier.getELiterals() %}
 {% set needsEnumLiteral = true %}
-{% if literal.getEAnnotations().size() > 0 %}{% set needsAnnotation = true %}{% endif %}
+{% if runtimeAnnotations(literal).length > 0 %}{% set needsAnnotation = true %}{% endif %}
 {% endfor %}
 {% else %}
 {% set needsDataType = true %}
@@ -104,10 +98,12 @@ export interface {{ pkgClass }} extends {{ useImport("EPackage", "types", {found
 {% set _ = useImport(factoryClassName(package), "root", {foundational: false}) %}
 {% set _ = useImport(factoryClassName(package) + "Impl", "impl", {foundational: false}) %}
 {% set _ = useImport("set" + pkgClass + "Ref", "impl", {file: pkgClass + "Ref", foundational: false}) %}
+{% set _ = useImport("register" + pkgClass + "Initializer", "impl", {file: pkgClass + "Ref", foundational: false}) %}
 
 {#-
-  Emits code reconstructing `element`'s real EAnnotations (source +
-  details) onto the runtime object built at `targetExpr`. Scoped to
+  Emits code reconstructing `element`'s EAnnotations (source + details) onto
+  the runtime object built at `targetExpr`, except the generator-only ones
+  (see runtimeAnnotations). Scoped to
   package/classifier/feature/enum-literal only - EOperations have no
   runtime representation in the converted metamodel yet, so there's
   nowhere for an operation-level annotation to attach (see NOTES.md).
@@ -155,7 +151,7 @@ export interface {{ pkgClass }} extends {{ useImport("EPackage", "types", {found
     everywhere else in this file (the metaclass for EStringToStringMapEntry doesn't exist yet at the
     point this code runs during self-construction); the ordinary branch has no such ordering problem and
     uses the real, public API (setDetailValue) directly. #}
-{% for annotation in element.getEAnnotations() %}
+{% for annotation in runtimeAnnotations(element) %}
     {
       const annotation = new EAnnotationImpl();
 {% if annotation.getSource() %}
@@ -207,14 +203,9 @@ export class {{ pkgClass }}Impl extends EPackageImpl implements {{ pkgClass }} {
   private static _instance: {{ pkgClass }}Impl | undefined;
 
   /**
-   * The one explicit entry point that constructs the singleton - call it
-   * yourself, with your own factory, before anything else in your program
-   * touches {{ pkgClass }}Impl.eINSTANCE, to use a custom factory (e.g. one
-   * overriding createX() to return your own derived classes). Whichever
-   * caller gets here FIRST wins; a later call with a *different* factory
-   * is logged and otherwise ignored, rather than silently replacing an
-   * already-in-use singleton or throwing on a caller who didn't cause the
-   * conflict.
+   * Constructs the package, if that hasn't happened yet, and returns it. To use your own factory
+   * (e.g. one returning subclasses), call this with it before anything reads `eINSTANCE`; a
+   * factory passed after construction is ignored with a warning.
    */
   static init(factory?: {{ factoryClassName(package) }}): {{ pkgClass }}Impl {
     if (!{{ pkgClass }}Impl._instance) {
@@ -235,10 +226,7 @@ export class {{ pkgClass }}Impl extends EPackageImpl implements {{ pkgClass }} {
 
   private constructor() {
     super();
-    // Set immediately, before Pass 1 constructs any classifier (each of
-    // which may need this reference - see {{ pkgClass }}Ref.ts's own doc
-    // comment for why this is a late-bound reference rather than a
-    // direct import of {{ pkgClass }}Impl.
+    // Set first: constructing the classifiers below already needs the package reference.
     set{{ pkgClass }}Ref(this);
 
     // Pass 1: create every classifier (empty shell - no features/supertypes
@@ -266,10 +254,7 @@ export class {{ pkgClass }}Impl extends EPackageImpl implements {{ pkgClass }} {
 {{ bootstrapSet("literal", "setLiteral", "Ids.EEnumLiteral.literal", jsString(literal.getLiteral())) }}
 {{ emitAnnotations("literal", literal) }}
 {% if options['generate-ecore'] %}
-      // No addLiteral() here - this generated EEnumImpl doesn't have that
-      // hand-written convenience method (it's not a reflective feature),
-      // so the list-add and the eEnum backpointer (a real, modeled,
-      // non-changeable opposite - see NOTES.md) are wired manually.
+      // eEnum is not changeable, so both ends of the opposite are set directly.
       this._{{ classifier.getName() }}.eBootstrapList(Ids.EEnum.eLiterals).add(literal);
       literal.eBasicSetValue(Ids.EEnumLiteral.eEnum, this._{{ classifier.getName() }});
 {% else %}
@@ -325,6 +310,9 @@ export class {{ pkgClass }}Impl extends EPackageImpl implements {{ pkgClass }} {
 {{ bootstrapSet(fieldExpr, "setChangeable", "Ids.EStructuralFeature.changeable", feature.isChangeable()) }}
 {{ bootstrapSet(fieldExpr, "setOrdered", "Ids.ETypedElement.ordered", feature.isOrdered()) }}
 {{ bootstrapSet(fieldExpr, "setUnique", "Ids.ETypedElement.unique", feature.isUnique()) }}
+{% if feature.getDefaultValueLiteral() !== undefined %}
+{{ bootstrapSet(fieldExpr, "setDefaultValueLiteral", "Ids.EStructuralFeature.defaultValueLiteral", jsString(feature.getDefaultValueLiteral())) }}
+{% endif %}
     {{ fieldExpr }}.setFeatureID(Ids.{{ classifier.getName() }}.{{ feature.getName() }});
     {#- containerClass: the concrete implementation class the feature is declared on - the closest
         TypeScript has to Java's own containerClass semantics (Class<?>, e.g. EClassifier.class in the
@@ -345,11 +333,8 @@ export class {{ pkgClass }}Impl extends EPackageImpl implements {{ pkgClass }} {
 {% endfor %}
 {% endfor %}
 
-    // Pass 2.5: operations and their parameters - real EOperation/EParameter objects, not just the
-    // generated METHODS (which already existed) - eOperations used to be permanently empty at runtime;
-    // this is what actually populates it, the same way pass 2 populates eStructuralFeatures. Kept as
-    // its own pass, after every classifier and feature exists (an operation's return type or a
-    // parameter's type can reference either), rather than folded into the loop above.
+    // Pass 2.5: operations and their parameters, after every classifier and feature exists, since
+    // their types can refer to any of them.
 {% for classifier in eClassesOf(package) %}
 {% for op in classifier.getEOperations() %}
 {% set opIndex = loop.index0 %}
@@ -406,21 +391,9 @@ export class {{ pkgClass }}Impl extends EPackageImpl implements {{ pkgClass }} {
 {% endfor %}
 {% endfor %}
 
-    // Pass 5 (recompute EAll* caches, ordinary mode only) removed - stale post-swap.
-    // @typemf/core's own EClassImpl is now itself generated code (see NOTES.md's point 6/7
-    // write-ups), using the same automatic, get-bodied caching (EObjectImpl.getModelGeneration(),
-    // point 1) as self-hosted output always did - there is no recomputeAllLists() method to call
-    // anymore, in either mode, and none is needed.
 
-    // Pass 6: set the package's own name/nsURI/nsPrefix/annotations last,
-    // deliberately - these go through the ordinary reflective setters
-    // (this.setName(), etc.), which need the "name"/etc. feature's own
-    // metaclass object to already exist (it's built above, in the passes
-    // this follows). Calling them earlier - before those metaclasses
-    // exist - is a genuine bootstrap-ordering bug, confirmed directly by
-    // reproducing it: this line order isn't a style choice, the metaclass
-    // shells and feature wiring above are a real, load-bearing
-    // precondition for the reflective setter calls below to work at all.
+    // Pass 5: the package's own name, nsURI, nsPrefix and annotations, last: the setters used here
+    // need the features built above.
     this.setName({{ jsString(package.getName()) }});
     this.setNsURI({{ jsString(package.getNsURI()) }});
     this.setNsPrefix({{ jsString(package.getNsPrefix()) }});
@@ -476,4 +449,9 @@ export class {{ pkgClass }}Impl extends EPackageImpl implements {{ pkgClass }} {
 {% endif %}
 {% endfor %}
 }
+
+// Lets get{{ pkgClass }}Ref() construct the package on first use.
+register{{ pkgClass }}Initializer(() => {
+  void {{ pkgClass }}Impl.eINSTANCE;
+});
 {% endfile %}

package/templates/typescript/epackageref.njk

@@ -2,43 +2,41 @@
 import type { {{ packageClassName(package) }} } from '../{{ packageClassName(package) }}.js';
 
 /**
- * A late-bound reference to the {{ packageClassName(package) }} singleton,
- * set once by {{ packageClassName(package) }}Impl's own constructor after
- * it finishes constructing itself.
- *
- * Every generated class needs a reference to the package singleton (for
- * eClass(), for feature-ID lookups in field initializers/lazy getters,
- * etc.) - and {{ packageClassName(package) }}Impl itself constructs
- * (nearly) every one of those classes to build the runtime metamodel. For
- * an ordinary generated package that mutual reference is harmless: the
- * package singleton already exists in full by the time anything else is
- * ever constructed. But self-hosting a metamodel that describes itself
- * (as with real Ecore.ecore) makes this a genuine, confirmed hazard: a
- * real class along the package's own superclass chain, or a class that is
- * ALSO the superclass of something the package constructs directly (the
- * "EFactory unification" / "EPackage unification" cases), can end up
- * needing this reference while {{ packageClassName(package) }}Impl is
- * still in the middle of constructing itself - a genuine circular
- * dependency, not merely an ordering preference, confirmed directly
- * against a real failing bundle ("Class extends value undefined is not a
- * constructor or null") while building this generator, not assumed.
- *
- * This module has only a type-only import (erased at compile time, zero
- * runtime footprint) - so importing FROM this module can never itself
- * participate in a circular dependency, unlike importing
- * {{ packageClassName(package) }}Impl (or anything re-exporting it)
- * directly.
+ * A reference to the {{ packageClassName(package) }} singleton that every generated class of the package
+ * reads instead of importing {{ packageClassName(package) }}Impl, which would be a circular import: the
+ * package constructs those classes while it constructs itself. This module only has a type
+ * import, so it can be imported from anywhere.
  */
 let ref: {{ packageClassName(package) }} | undefined;
 
+/** Constructs the package on first use; registered when {{ packageClassName(package) }}Impl.ts is evaluated. */
+let initializer: (() => void) | undefined;
+let initializing = false;
+
 export function set{{ packageClassName(package) }}Ref(pkg: {{ packageClassName(package) }}): void {
   ref = pkg;
 }
 
+export function register{{ packageClassName(package) }}Initializer(init: () => void): void {
+  initializer = init;
+}
+
 export function get{{ packageClassName(package) }}Ref(): {{ packageClassName(package) }} {
+  // `initializing` turns a reentrant call during construction into the error below.
+  if (!ref && initializer && !initializing) {
+    initializing = true;
+    try {
+      initializer();
+    } finally {
+      initializing = false;
+    }
+  }
   if (!ref) {
     throw new Error(
-      'get{{ packageClassName(package) }}Ref() called before the {{ packageClassName(package) }} singleton finished constructing itself.'
+      'get{{ packageClassName(package) }}Ref() called before the {{ packageClassName(package) }} singleton finished constructing itself, and no ' +
+        'initializer was registered to construct it on demand - this means {{ packageClassName(package) }}Impl.ts\'s own module ' +
+        'was never evaluated at all (an unusual bundler/tree-shaking setup). Call {{ packageClassName(package) }}Impl.eINSTANCE ' +
+        'or .init() yourself first, or check that this package is marked side-effectful.'
     );
   }
   return ref;

package/templates/typescript/etypeguards.njk

@@ -1,22 +1,8 @@
 {% file "util/" + typeGuardsClassName(package) + ".ts" %}
 /**
- * Runtime type guards, one per classifier declared in types/ - the
- * reflective counterpart to a hand-written structural guard like
- *
- *   function isReference(feature: EStructuralFeature): feature is EReference {
- *     return "isContainment" in feature;
- *   }
- *
- * Structural (duck-typing) checks like that one work when a single
- * classifier has some genuinely distinguishing own member - but nothing
- * guarantees an arbitrary generated classifier has one (a subclass might
- * add no own features at all, inheriting everything). These guards check
- * the object's REAL runtime EClass against the metamodel's own
- * eAllSuperTypes reflectively instead (via isSuperTypeOf()), which is
- * correct for every classifier unconditionally, including abstract ones
- * (correctly true for any instance of a concrete subclass) and dynamic
- * instances (no dependency on the object's actual JS class/prototype at
- * all, unlike `instanceof`).
+ * Type guards for the classifiers of the package. They check an object's class with
+ * `isSuperTypeOf()`, so they also work for abstract classes, interfaces and dynamic objects,
+ * unlike `instanceof`.
  */
 function hasEClass(obj: unknown): obj is {{ useImport("EObject", "types", {foundational: true}) }} {
   return obj !== null && typeof obj === 'object' && typeof (obj as { eClass?: unknown }).eClass === 'function';