Add Type-safe strings for Number, Integer, Float

Schema.org Numbers, Integers, and Floats support being assigned to
strings with the appropriate fromat (e.g. "4394" for Integer). With
TypeScript 4.1.0 and beyond, this can be expressed with the
`` `${number}` `` type. This pushes the minimum required version for
schema-dts from 3.4.0 to 4.1.0, and is thus a breaking change.

Note there's a future situation where we would RESTRICT the `Integer`
type further; so that only valid integral numbers are assignable to it.
This will be another breaking change for another time, when TypeScript
can finally represent this.

Fixes #130.

Author: Eyas

dist/schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schema-dts",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "displayName": "schema-dts: Strongly-typed Schema.org vocabulary declarations",
   "description": "A TypeScript package with latest Schema.org Schema Typings",
   "authors": [
@@ -17,7 +17,7 @@
   "devDependencies": {},
   "dependencies": {},
   "peerDependencies": {
-    "typescript": ">=3.4.0"
+    "typescript": ">=4.1.0"
   },
   "keywords": [
     "typescript",

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "schema-dts-gen",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "displayName": "schema-dts Generator",
   "description": "Generate TypeScript Definitions for Schema.org Schema",
   "authors": [
@@ -54,7 +54,7 @@
     "rxjs": "^7.2.0"
   },
   "peerDependencies": {
-    "typescript": ">=3.4.0"
+    "typescript": ">=4.1.0"
   },
   "nyc": {
     "extension": [

package.json

@@ -39,12 +39,18 @@ function toClass(cls: Class, topic: Topic, map: ClassMap): Class {
 }
 
 const wellKnownTypes = [
-  new AliasBuiltin('http://schema.org/Text', 'string'),
-  new AliasBuiltin('http://schema.org/Number', 'number'),
-  new AliasBuiltin('http://schema.org/Time', 'string'),
-  new AliasBuiltin('http://schema.org/Date', 'string'),
-  new AliasBuiltin('http://schema.org/DateTime', 'string'),
-  new AliasBuiltin('http://schema.org/Boolean', 'boolean'),
+  new AliasBuiltin('http://schema.org/Text', AliasBuiltin.Alias('string')),
+  // IMPORTANT: In the future, if possible, we should have: `${number}` in Float only,
+  // an integer string literal in Integer only, and Number becomes simply Float|Integer.
+  new AliasBuiltin(
+    'http://schema.org/Number',
+    AliasBuiltin.Alias('number'),
+    AliasBuiltin.NumberStringLiteral()
+  ),
+  new AliasBuiltin('http://schema.org/Time', AliasBuiltin.Alias('string')),
+  new AliasBuiltin('http://schema.org/Date', AliasBuiltin.Alias('string')),
+  new AliasBuiltin('http://schema.org/DateTime', AliasBuiltin.Alias('string')),
+  new AliasBuiltin('http://schema.org/Boolean', AliasBuiltin.Alias('boolean')),
 ];
 
 // Should we allow 'string' to be a valid type for all values of this type?
@@ -85,7 +91,7 @@ function ForwardDeclareClasses(topics: readonly TypedTopic[]): ClassMap {
     const allowString = wellKnownStrings.some(wks =>
       wks.equivTo(topic.Subject)
     );
-    if (allowString) cls.addTypedef('string');
+    if (allowString) cls.addTypedef(AliasBuiltin.Alias('string'));
 
     classes.set(topic.Subject.toString(), cls);
   }

src/transform/toClass.ts

@@ -61,7 +61,7 @@ export type ClassMap = Map<string, Class>;
  */
 export class Class {
   private _comment?: string;
-  private _typedef?: string;
+  private _typedefs: TypeNode[] = [];
   private readonly children: Class[] = [];
   private readonly _parents: Class[] = [];
   private readonly _props: Set<Property> = new Set();
@@ -97,11 +97,15 @@ export class Class {
     return appendLine(this._comment, deprecated);
   }
 
-  protected get typedefs(): string[] {
+  protected get typedefs(): TypeNode[] {
+    const f: TypeNode = undefined!;
+
     const parents = this.allParents().flatMap(p => p.typedefs);
     return Array.from(
-      new Set(this._typedef ? [this._typedef, ...parents] : parents)
-    ).sort();
+      new Map([...this._typedefs, ...parents].map(t => [JSON.stringify(t), t]))
+    )
+      .sort(([key1, value1], [key2, value2]) => key1.localeCompare(key2))
+      .map(([_, value]) => value);
   }
 
   private properties() {
@@ -198,13 +202,8 @@ export class Class {
     return false;
   }
 
-  addTypedef(typedef: string) {
-    if (this._typedef) {
-      throw new Error(
-        `Class ${this.subject.href} already has typedef ${this._typedef} but we're also adding ${typedef}`
-      );
-    }
-    this._typedef = typedef;
+  addTypedef(typedef: TypeNode) {
+    this._typedefs.push(typedef);
   }
 
   addProp(p: Property) {
@@ -299,7 +298,7 @@ export class Class {
 
   protected nonEnumType(skipDeprecated: boolean): TypeNode[] {
     this.children.sort((a, b) => CompareKeys(a.subject, b.subject));
-    const children = this.children
+    const children: TypeNode[] = this.children
       .filter(child => !(child.deprecated && skipDeprecated))
       .map(child =>
         factory.createTypeReferenceNode(
@@ -309,11 +308,7 @@ export class Class {
       );
 
     // A type can have a valid typedef, add that if so.
-    children.push(
-      ...this.typedefs.map(t =>
-        factory.createTypeReferenceNode(t, /*typeArgs=*/ [])
-      )
-    );
+    children.push(...this.typedefs);
 
     const upRef = this.leafName() || this.baseName();
     return upRef
@@ -379,9 +374,25 @@ export class Builtin extends Class {}
  * in JSON-LD and JavaScript as a typedef to a native type.
  */
 export class AliasBuiltin extends Builtin {
-  constructor(url: string, equivTo: string) {
+  constructor(url: string, ...equivTo: TypeNode[]) {
     super(UrlNode.Parse(url));
-    this.addTypedef(equivTo);
+    for (const t of equivTo) this.addTypedef(t);
+  }
+
+  static Alias(equivTo: string): TypeNode {
+    return factory.createTypeReferenceNode(equivTo, /*typeArgs=*/ []);
+  }
+
+  static NumberStringLiteral(): TypeNode {
+    return factory.createTemplateLiteralType(
+      factory.createTemplateHead(/* text= */ ''),
+      [
+        factory.createTemplateLiteralTypeSpan(
+          factory.createTypeReferenceNode('number'),
+          factory.createTemplateTail(/* text= */ '')
+        ),
+      ]
+    );
   }
 }
 

src/ts/class.ts

@@ -86,7 +86,7 @@ type IdReference = {
  * - Use values from 0123456789 (Unicode 'DIGIT ZERO' (U+0030) to 'DIGIT NINE' (U+0039)) rather than superficially similiar Unicode symbols.
  * - Use '.' (Unicode 'FULL STOP' (U+002E)) rather than ',' to indicate a decimal point. Avoid using these symbols as a readability separator.
  */
-export type Number = number;
+export type Number = number | \`\${number}\`;
 
 /** Data type: Text. */
 export type Text = string;

test/baselines/comments_test.ts

@@ -57,7 +57,7 @@ type IdReference = {
     \\"@id\\": string;
 };
 
-export type Number = number;
+export type Number = number | \`\${number}\`;
 
 export type Text = string;
 

test/baselines/data_type_union_test.ts

@@ -80,7 +80,7 @@ type IdReference = {
     \\"@id\\": string;
 };
 
-export type Number = number;
+export type Number = number | \`\${number}\`;
 
 export type Text = string;
 

test/baselines/deprecated_objects_test.ts

@@ -61,7 +61,7 @@ type IdReference = {
     \\"@id\\": string;
 };
 
-export type Number = number;
+export type Number = number | \`\${number}\`;
 
 export type Text = string;
 

test/baselines/inheritance_multiple_test.ts

@@ -56,7 +56,7 @@ type IdReference = {
     \\"@id\\": string;
 };
 
-export type Number = number;
+export type Number = number | \`\${number}\`;
 
 export type Text = string;