chore(TS) Revise typescript interface for Concerto 1.0

Signed-off-by: Jerome Simeon <[email protected]>

packages/concerto-core/api.txt

@@ -38,14 +38,14 @@ class AssetDeclaration extends IdentifiedDeclaration {
    + boolean hasInstance(object) 
 }
 class ClassDeclaration extends Decorated {
-   + void constructor(ModelFile,string) throws IllegalModelException
+   + void constructor(ModelFile,Object) throws IllegalModelException
    + ClassDeclaration _resolveSuperType() 
    + boolean isAbstract() 
    + boolean isEnum() 
    + boolean isConcept() 
    + boolean isEvent() 
    + string getName() 
-   + String getNamespace() 
+   + string getNamespace() 
    + string getFullyQualifiedName() 
    + Boolean isIdentified() 
    + Boolean isSystemIdentified() 
@@ -96,11 +96,19 @@ class IdentifiedDeclaration extends ClassDeclaration {
    + void constructor(ModelFile,Object) throws IllegalModelException
    + boolean hasInstance(object) 
 }
+class IllegalModelException extends BaseFileException {
+   + void constructor(string,ModelFile,Object,number,number,number,number,string) 
+}
 class Introspector {
    + void constructor(ModelManager) 
    + ClassDeclaration[] getClassDeclarations() 
    + ClassDeclaration getClassDeclaration(String) throws Error
 }
+class ModelFileDownloader {
+   + void constructor(ModelFileLoader,Number) 
+   + Promise downloadExternalDependencies(ModelFile[],Object) 
+   + Promise runJob(Object,Object) 
+}
 class ModelFile {
    + void constructor(ModelManager,string,string) throws IllegalModelException
    + Boolean isSystemModelFile() 
@@ -203,22 +211,22 @@ class ModelManager {
    + Object[] addModelFiles(object[],undefined,boolean) 
    + void validateModelFiles() 
    + Promise updateExternalModels(Object,ModelFileDownloader) throws IllegalModelException
-   + void writeModelsToFileSystem(String,Object,boolean) 
+   + void writeModelsToFileSystem(string,Object,boolean) 
    + Object[] getModels(Object,boolean) 
    + void clearModelFiles() 
    + ModelFile getModelFile(string) 
    + string[] getNamespaces() 
-   + AssetDeclaration[] getAssetDeclarations(Boolean) 
-   + TransactionDeclaration[] getTransactionDeclarations(Boolean) 
-   + EventDeclaration[] getEventDeclarations(Boolean) 
-   + ParticipantDeclaration[] getParticipantDeclarations(Boolean) 
-   + EnumDeclaration[] getEnumDeclarations(Boolean) 
-   + ConceptDeclaration[] getConceptDeclarations(Boolean) 
+   + AssetDeclaration[] getAssetDeclarations() 
+   + TransactionDeclaration[] getTransactionDeclarations() 
+   + EventDeclaration[] getEventDeclarations() 
+   + ParticipantDeclaration[] getParticipantDeclarations() 
+   + EnumDeclaration[] getEnumDeclarations() 
+   + ConceptDeclaration[] getConceptDeclarations() 
    + Factory getFactory() 
    + Serializer getSerializer() 
    + DecoratorFactory[] getDecoratorFactories() 
    + void addDecoratorFactory(DecoratorFactory) 
-   + boolean derivesFrom(String,String) 
+   + boolean derivesFrom(string,string) 
    + boolean hasInstance(object) 
 }
 class SecurityException extends BaseException {
@@ -231,3 +239,14 @@ class Serializer {
    + Resource fromJSON(Object,Object,boolean,boolean,number) 
    + boolean hasInstance(object) 
 }
+class TypedStack {
+   + void constructor(Object) 
+   + void push(Object,Object) 
+   + Object pop(Object) 
+   + Object peek(Object) 
+   + void clear() 
+}
+class TypeNotFoundException extends BaseException {
+   + void constructor(string,string,string) 
+   + string getTypeName() 
+}

packages/concerto-core/changelog.txt

@@ -24,9 +24,8 @@
 # Note that the latest public API is documented using JSDocs and is available in api.txt.
 #
 
-Version 1.0.3 {f7a73e6f74c7c012aeb923b07010244a} 2021-06-25
-- Make ModelManager.getModelFile public
-- Make ModelManager.accept public
+Version 1.0.3 {1fe469fe1a79af5d5a4f5ec7dee6b7d4} 2021-06-25
+- Aligns JSDoc and the TypeScript interface
 
 Version 1.0.0-alpha.8 {08b0c809336354e7d1b17a2e44fca8b0} 2021-04-22
 - Add datetimeutil & Consolidate UTC offset support

packages/concerto-core/index.js

@@ -21,36 +21,84 @@
  * @module concerto-core
  */
 
-module.exports.AssetDeclaration = require('./lib/introspect/assetdeclaration');
+// Exceptions
 module.exports.BaseException = require('./lib/baseexception');
 module.exports.BaseFileException = require('./lib/basefileexception');
+module.exports.ParseException = require('./lib/introspect/parseexception');
+module.exports.SecurityException = require('./lib/securityexception');
+module.exports.IllegalModelException = require('./lib/introspect/illegalmodelexception');
+module.exports.TypeNotFoundException = require('./lib/typenotfoundexception');
+
+// Decorated
+module.exports.Decorator = require('./lib/introspect/decorator');
+module.exports.DecoratorFactory = require('./lib/introspect/decoratorfactory');
+
+// ClassDeclarations
 module.exports.ClassDeclaration = require('./lib/introspect/classdeclaration');
+module.exports.IdentifiedDeclaration = require('./lib/introspect/identifieddeclaration');
+module.exports.AssetDeclaration = require('./lib/introspect/assetdeclaration');
 module.exports.ConceptDeclaration = require('./lib/introspect/conceptdeclaration');
-module.exports.DateTimeUtil = require('./lib/datetimeutil');
-module.exports.EnumDeclaration = require('./lib/introspect/enumdeclaration');
 module.exports.EnumValueDeclaration = require('./lib/introspect/enumvaluedeclaration');
 module.exports.EventDeclaration = require('./lib/introspect/eventdeclaration');
+module.exports.ParticipantDeclaration = require('./lib/introspect/participantdeclaration');
+module.exports.TransactionDeclaration = require('./lib/introspect/transactiondeclaration');
+
+// Properties
+module.exports.Property = require('./lib/introspect/property');
 module.exports.Field = require('./lib/introspect/field');
+module.exports.EnumDeclaration = require('./lib/introspect/enumdeclaration');
+module.exports.RelationshipDeclaration = require('./lib/introspect/relationshipdeclaration');
+
+// Typed
+module.exports.Typed = require('./lib/model/typed');
+
+// Identifiables
+module.exports.Identifiable = require('./lib/model/identifiable');
+module.exports.Relationship = require('./lib/model/relationship');
+module.exports.Resource = require('./lib/model/resource');
+
+// Writers
 module.exports.Writer = require('./lib/writer');
+
+// Factory
 module.exports.Factory = require('./lib/factory');
+
+// Globalize
 module.exports.Globalize = require('./lib/globalize');
+
+// Introspector
 module.exports.Introspector = require('./lib/introspect/introspector');
-module.exports.Logger = require('./lib/logger');
+
+// ModelFile
 module.exports.ModelFile = require('./lib/introspect/modelfile');
-module.exports.ModelLoader = require('./lib/modelloader');
+
+// ModelManager
 module.exports.ModelManager = require('./lib/modelmanager');
-module.exports.DefaultModelFileLoader = require('./lib/introspect/loaders/defaultmodelfileloader');
-module.exports.ParseException = require('./lib/introspect/parseexception');
-module.exports.ParticipantDeclaration = require('./lib/introspect/participantdeclaration');
-module.exports.Property = require('./lib/introspect/property');
-module.exports.Relationship = require('./lib/model/relationship');
-module.exports.RelationshipDeclaration = require('./lib/introspect/relationshipdeclaration');
-module.exports.Resource = require('./lib/model/resource');
-module.exports.SecurityException = require('./lib/securityexception');
+
+// Serializer
 module.exports.Serializer = require('./lib/serializer');
-module.exports.TransactionDeclaration = require('./lib/introspect/transactiondeclaration');
-module.exports.Typed = require('./lib/model/typed');
-module.exports.TypedStack = require('./lib/serializer/typedstack');
+
+// ModelUtil
 module.exports.ModelUtil = require('./lib/modelutil');
+
+// ModelFileLoaders
+module.exports.DefaultModelFileLoader = require('./lib/introspect/loaders/defaultmodelfileloader');
+
+// ModelLoader
+module.exports.ModelLoader = require('./lib/modelloader');
+
+
+// DateTimeUtil
+module.exports.DateTimeUtil = require('./lib/datetimeutil');
+
+// Logger
+module.exports.Logger = require('./lib/logger');
+
+// TypedStack
+module.exports.TypedStack = require('./lib/serializer/typedstack');
+
+// Concerto
+module.exports.Concerto = require('./lib/concerto');
+
+// Version
 module.exports.version = require('./package.json');
-module.exports.Concerto = require('./lib/concerto');

packages/concerto-core/lib/baseexception.js

@@ -23,7 +23,6 @@ const packageJson = require('../package.json');
 * @memberof module:concerto-core
 */
 class BaseException extends Error {
-
     /**
      * Create the BaseException.
      * @param {string} message - The exception message.

packages/concerto-core/lib/basefileexception.js

@@ -24,14 +24,13 @@ const BaseException = require('./baseexception');
  * @memberof module:concerto-core
  */
 class BaseFileException extends BaseException {
-
     /**
      * Create an BaseFileException
      * @param {string} message - the message for the exception
      * @param {string} fileLocation - the optional file location associated with the exception
      * @param {string} fullMessage - the optional full message text
-     * @param {string} fileName - the optional file name
-      * @param {string} component - the optional component which throws this error
+     * @param {string} [fileName] - the file name
+     * @param {string} [component] - the component which throws this error
      */
     constructor(message, fileLocation, fullMessage, fileName, component) {
         super(fullMessage ? fullMessage : message, component);

packages/concerto-core/lib/concerto.js

@@ -26,7 +26,6 @@ const ObjectValidator = require('./serializer/objectvalidator');
  * @memberof module:concerto-core
  */
 class Concerto {
-
     /**
      * Create a Concerto instance.
      * @param {*} modelManager - The this.modelManager to use for validation etc.

packages/concerto-core/lib/factory.js

@@ -45,7 +45,6 @@ dayjs.extend(utc);
  * @memberof module:concerto-core
  */
 class Factory {
-
     /**
      * Create the factory.
      *

packages/concerto-core/lib/introspect/assetdeclaration.js

@@ -28,7 +28,6 @@ const IdentifiedDeclaration = require('./identifieddeclaration');
  * @memberof module:concerto-core
  */
 class AssetDeclaration extends IdentifiedDeclaration {
-
     /**
      * Create an AssetDeclaration.
      * @param {ModelFile} modelFile the ModelFile for this class

packages/concerto-core/lib/introspect/classdeclaration.js

@@ -36,13 +36,12 @@ const RelationshipDeclaration = require('./relationshipdeclaration');
  * @memberof module:concerto-core
  */
 class ClassDeclaration extends Decorated {
-
     /**
      * Create a ClassDeclaration from an Abstract Syntax Tree. The AST is the
      * result of parsing.
      *
      * @param {ModelFile} modelFile - the ModelFile for this class
-     * @param {string} ast - the AST created by the parser
+     * @param {Object} ast - the AST created by the parser
      * @throws {IllegalModelException}
      */
     constructor(modelFile, ast) {
@@ -57,7 +56,6 @@ class ClassDeclaration extends Decorated {
      * @private
      */
     process() {
-
         super.process();
 
         this.name = this.ast.id.name;
@@ -185,7 +183,6 @@ class ClassDeclaration extends Decorated {
      * @private
      */
     validate() {
-
         super.validate();
 
         const declarations = this.getModelFile().getAllDeclarations();
@@ -325,7 +322,7 @@ class ClassDeclaration extends Decorated {
 
     /**
      * Return the namespace of this class.
-     * @return {String} namespace - a namespace.
+     * @return {string} namespace - a namespace.
      */
     getNamespace() {
         return this.modelFile.getNamespace();
@@ -371,10 +368,9 @@ class ClassDeclaration extends Decorated {
      * Returns the name of the identifying field for this class. Note
      * that the identifying field may come from a super type.
      *
-     * @return {string} the name of the id field for this class
+     * @return {string} the name of the id field for this class or null if it does not exist
      */
     getIdentifierFieldName() {
-
         if (this.idField) {
             return this.idField;
         } else {
@@ -400,7 +396,7 @@ class ClassDeclaration extends Decorated {
      * not introspected.
      *
      * @param {string} name the name of the field
-     * @return {Property} the field definition or null if it does not exist.
+     * @return {Property} the field definition or null if it does not exist
      */
     getOwnProperty(name) {
         for (let n = 0; n < this.properties.length; n++) {

packages/concerto-core/lib/introspect/conceptdeclaration.js

@@ -28,7 +28,6 @@ const ClassDeclaration = require('./classdeclaration');
  * @memberof module:concerto-core
  */
 class ConceptDeclaration extends ClassDeclaration {
-
     /**
      * Create a ConceptDeclaration.
      * @param {ModelFile} modelFile the ModelFile for this class

packages/concerto-core/lib/introspect/decorated.js

@@ -26,7 +26,6 @@ const IllegalModelException = require('./illegalmodelexception');
  * @memberof module:concerto-core
  */
 class Decorated {
-
     /**
      * Create a Decorated from an Abstract Syntax Tree. The AST is the
      * result of parsing.

packages/concerto-core/lib/introspect/decorator.js

@@ -20,7 +20,6 @@
  * @memberof module:concerto-core
  */
 class Decorator {
-
     /**
      * Create a Decorator.
      * @param {ClassDeclaration | Property} parent - the owner of this property
@@ -79,7 +78,6 @@ class Decorator {
      */
     validate() {}
 
-
     /**
      * Returns the name of a decorator
      * @return {string} the name of this decorator
@@ -90,7 +88,7 @@ class Decorator {
 
     /**
      * Returns the arguments for this decorator
-     * @return {object[]} the arguments for this decorator or null if it does not have any arguments
+     * @return {object[]} the arguments for this decorator
      */
     getArguments() {
         return this.arguments;

packages/concerto-core/lib/introspect/decoratorfactory.js

@@ -21,7 +21,6 @@
  * @memberof module:concerto-core
  */
 class DecoratorFactory {
-
     /**
      * Process the decorator, and return a specific implementation class for that
      * decorator, or return null if this decorator is not handled by this processor.

packages/concerto-core/lib/introspect/enumdeclaration.js

@@ -25,9 +25,8 @@ const ClassDeclaration = require('./classdeclaration');
  * @memberof module:concerto-core
  */
 class EnumDeclaration extends ClassDeclaration {
-
     /**
-     * Create an AssetDeclaration.
+     * Create an EnumDeclaration.
      * @param {ModelFile} modelFile the ModelFile for this class
      * @param {Object} ast - The AST created by the parser
      * @throws {IllegalModelException}

packages/concerto-core/lib/introspect/enumvaluedeclaration.js

@@ -25,7 +25,6 @@ const Property = require('./property');
  * @memberof module:concerto-core
  */
 class EnumValueDeclaration extends Property {
-
     /**
      * Create a EnumValueDeclaration.
      * @param {ClassDeclaration} parent - The owner of this property

packages/concerto-core/lib/introspect/field.js

@@ -29,9 +29,8 @@ const StringValidator = require('./stringvalidator');
  * @memberof module:concerto-core
  */
 class Field extends Property {
-
     /**
-     * Create an Field.
+     * Create a Field.
      * @param {ClassDeclaration} parent - The owner of this property
      * @param {Object} ast - The AST created by the parser
      * @throws {IllegalModelException}