@sdeverywhere/build 0.3.3 → 0.3.5

package/dist/index.d.cts

@@ -8,10 +8,14 @@ type LogLevel = 'error' | 'info' | 'verbose';
  */
 type BuildMode = 'development' | 'production';
 
+/** A variable name as used in the modeling tool. */
+type VarName = string;
 /**
  * Describes a model input variable.
  */
 interface InputSpec {
+    /** The variable name (as used in the modeling tool). */
+    varName: VarName;
     /**
      * The stable input identifier.  It is recommended to set this to a value (for example, a
      * numeric string like what `plugin-config` uses) that is separate from `varName` and is
@@ -21,33 +25,164 @@ interface InputSpec {
      * note that this approach will be less resilient to renames.
      */
     inputId?: string;
-    /** The variable name (as used in the modeling tool). */
-    varName: string;
     /** The default value for the input. */
-    defaultValue: number;
+    defaultValue?: number;
     /** The minimum value for the input. */
-    minValue: number;
+    minValue?: number;
     /** The maximum value for the input. */
-    maxValue: number;
+    maxValue?: number;
 }
 /**
  * Describes a model output variable.
  */
 interface OutputSpec {
     /** The variable name (as used in the modeling tool). */
-    varName: string;
+    varName: VarName;
 }
 /**
  * Describes a model (e.g., a Vensim mdl file) and the input/output variables
- * that should be included in the model generated by SDE.
+ * that should be included in the model generated by SDEverywhere.
  */
 interface ModelSpec {
-    /** The input variable specs. */
+    /**
+     * The input variables for the model.  This can either be a simple array of
+     * input variable names, or an array of `InputSpec` instances.
+     *
+     * The builder requires only variable names for the purposes of generating
+     * a model, but some plugins may require full `InputSpec` instances.
+     */
+    inputs: VarName[] | InputSpec[];
+    /**
+     * The output variables for the model.  This can either be a simple array of
+     * output variable names, or an array of `OutputSpec` instances.
+     */
+    outputs: VarName[] | OutputSpec[];
+    /**
+     * The dat files that provide the data for exogenous data variables in the
+     * model.
+     */
+    datFiles?: string[];
+    /**
+     * Whether to bundle a model listing with the generated model.
+     *
+     * If undefined, defaults to false.
+     *
+     * When this is true, a model listing will be bundled with the generated
+     * model to allow the `runtime` package to resolve variables that are
+     * referenced by name or identifier.  This listing will increase the size
+     * of the generated model, so it is recommended to set this to true only
+     * if it is needed.
+     */
+    bundleListing?: boolean;
+    /**
+     * Whether to allow lookups to be overridden at runtime using `setLookup`.
+     *
+     * If undefined or false, the generated model will implement `setLookup`
+     * as a no-op, meaning that lookups cannot be overridden at runtime.
+     *
+     * If true, all lookups in the generated model will be available to be
+     * overridden.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be overridden.
+     */
+    customLookups?: boolean | VarName[];
+    /**
+     * Whether to allow for capturing the data for arbitrary variables at
+     * runtime (including variables that are not configured in the `outputs`
+     * array).
+     *
+     * If undefined or false, the generated model will implement `storeOutput`
+     * as a no-op, meaning that the data for arbitrary variables cannot be
+     * captured at runtime.
+     *
+     * If true, all variables in the generated model will be available to be
+     * captured at runtime.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be captured at runtime.
+     */
+    customOutputs?: boolean | VarName[];
+    /** Additional options included with the SDE `spec.json` file. */
+    options?: {
+        [key: string]: any;
+    };
+}
+/**
+ * Describes a model (e.g., a Vensim mdl file) and the input/output variables
+ * that should be included in the model generated by SDEverywhere.  This is
+ * largely the same as the `ModelSpec` interface, except this one has been
+ * fully resolved (paths have been validated, input and output variables have
+ * been checked, etc).  This is the spec object that will be passed to plugin
+ * functions.
+ */
+interface ResolvedModelSpec {
+    /**
+     * The input variable names for the model.  This will be defined regardless
+     * of whether `ModelSpec.inputs` was defined as an array of variable names
+     * or an array of `InputSpec` instances.  (The input variable names are
+     * derived from the `InputSpec` instances as needed.)
+     */
+    inputVarNames: VarName[];
+    /**
+     * The input variable specs for the model.
+     */
     inputs: InputSpec[];
-    /** The output variable specs. */
+    /**
+     * The output variable names for the model.  This will be defined regardless
+     * of whether `ModelSpec.outputs` was defined as an array of variable names
+     * or an array of `OutputSpec` instances.  (The output variable names are
+     * derived from the `OutputSpec` instances as needed.)
+     */
+    outputVarNames: VarName[];
+    /**
+     * The output variable specs for the model.
+     */
     outputs: OutputSpec[];
-    /** The dat files to be included with the SDE `spec.json` file. */
+    /**
+     * The dat files that provide the data for exogenous data variables in the
+     * model.
+     */
     datFiles: string[];
+    /**
+     * Whether to bundle a model listing with the generated model.
+     *
+     * When this is true, a model listing will be bundled with the generated
+     * model to allow the `runtime` package to resolve variables that are
+     * referenced by name or identifier.  This listing will increase the size
+     * of the generated model, so it is recommended to set this to true only
+     * if it is needed.
+     */
+    bundleListing: boolean;
+    /**
+     * Whether to allow lookups to be overridden at runtime using `setLookup`.
+     *
+     * If false, the generated model will contain a `setLookup` function that
+     * throws an error, meaning that lookups cannot be overridden at runtime.
+     *
+     * If true, all lookups in the generated model will be available to be
+     * overridden.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be overridden.
+     */
+    customLookups: boolean | VarName[];
+    /**
+     * Whether to allow for capturing the data for arbitrary variables at
+     * runtime (including variables that are not configured in the `outputs`
+     * array).
+     *
+     * If false, the generated model will contain a `storeOutput` function
+     * that throws an error, meaning that the data for arbitrary variables
+     * cannot be captured at runtime.
+     *
+     * If true, all variables in the generated model will be available to be
+     * captured at runtime.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be captured at runtime.
+     */
+    customOutputs: boolean | VarName[];
     /** Additional options included with the SDE `spec.json` file. */
     options?: {
         [key: string]: any;
@@ -88,6 +223,17 @@ interface ResolvedConfig {
      * can be paths to files or glob patterns (relative to the project directory).
      */
     watchPaths: string[];
+    /**
+     * The code format to generate.  If 'js', the model will be compiled to a JavaScript
+     * file.  If 'c', the model will be compiled to a C file (in which case an additional
+     * plugin will be needed to convert the C code to a WebAssembly module).
+     */
+    genFormat: 'js' | 'c';
+    /**
+     * The absolute path to the JSON file that will be written by the build process that
+     * lists all dimensions and variables in the model.
+     */
+    outListingFile?: string;
     /**
      * The path to the `@sdeverywhere/cli` package.  This is currently only used to get
      * access to the files in the `src/c` directory.
@@ -272,8 +418,8 @@ declare class BuildContext {
  *   - preGenerate
  *       - preProcessMdl
  *       - postProcessMdl
- *       - preGenerateC
- *       - postGenerateC
+ *       - preGenerateCode
+ *       - postGenerateCode
  *   - postGenerate
  *   - postBuild
  *   - watch (only called once after initial build steps when mode==development)
@@ -292,7 +438,7 @@ interface Plugin {
      * @param context The build context (for logging, etc).
      * @param modelSpec The spec that controls how the model is generated.
      */
-    preGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<void>;
+    preGenerate?(context: BuildContext, modelSpec: ResolvedModelSpec): Promise<void>;
     /**
      * Called before SDE preprocesses the mdl file (in the case of one mdl file),
      * or before SDE flattens the mdl files (in the case of multiple mdl files).
@@ -310,19 +456,21 @@ interface Plugin {
      */
     postProcessMdl?(context: BuildContext, mdlContent: string): Promise<string>;
     /**
-     * Called before SDE generates a C file from the mdl file.
+     * Called before SDE generates a JS or C file from the mdl file.
      *
      * @param context The build context (for logging, etc).
+     * @param format The generated code format, either 'js' or 'c'.
      */
-    preGenerateC?(context: BuildContext): Promise<void>;
+    preGenerateCode?(context: BuildContext, format: 'js' | 'c'): Promise<void>;
     /**
-     * Called after SDE generates a C file from the mdl file.
+     * Called after SDE generates a JS or C file from the mdl file.
      *
      * @param context The build context (for logging, etc).
-     * @param cContent The resulting C file content.
-     * @return The modified C file content (if postprocessing was needed).
+     * @param format The generated code format, either 'js' or 'c'.
+     * @param content The resulting JS or C file content.
+     * @return The modified JS or C file content (if postprocessing was needed).
      */
-    postGenerateC?(context: BuildContext, cContent: string): Promise<string>;
+    postGenerateCode?(context: BuildContext, format: 'js' | 'c', content: string): Promise<string>;
     /**
      * Called after the "generate model" process has completed (but before the staged
      * files are copied to their destination).
@@ -332,7 +480,7 @@ interface Plugin {
      * @return Whether the plugin succeeded (for example, a plugin that runs tests can
      * return false to indicate that one or more tests failed).
      */
-    postGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<boolean>;
+    postGenerate?(context: BuildContext, modelSpec: ResolvedModelSpec): Promise<boolean>;
     /**
      * Called after the model has been generated and after the staged files
      * have been copied to their destination.
@@ -342,7 +490,7 @@ interface Plugin {
      * @return Whether the plugin succeeded (for example, a plugin that runs tests can
      * return false to indicate that one or more tests failed).
      */
-    postBuild?(context: BuildContext, modelSpec: ModelSpec): Promise<boolean>;
+    postBuild?(context: BuildContext, modelSpec: ResolvedModelSpec): Promise<boolean>;
     /**
      * Called in development/watch mode after the initial build has completed
      * (i.e., after the model has been generated and after the staged files
@@ -384,6 +532,19 @@ interface UserConfig {
      * If left undefined, this will resolve to the `modelFiles` array.
      */
     watchPaths?: string[];
+    /**
+     * The code format to generate.  If 'js', the model will be compiled to a JavaScript
+     * file.  If 'c', the model will be compiled to a C file (in which case an additional
+     * plugin will be needed to convert the C code to a WebAssembly module).  If undefined,
+     * defaults to 'js'.
+     */
+    genFormat?: 'js' | 'c';
+    /**
+     * If defined, the build process will write a JSON file to the provided path that lists
+     * all dimensions and variables in the model.  This can be an absolute path, or if it
+     * is a relative path it will be resolved relative to the `rootDir` for the project.
+     */
+    outListingFile?: string;
     /**
      * The array of plugins that are used to customize the build process.  These will be
      * executed in the order defined here.
@@ -437,4 +598,4 @@ interface BuildResult {
  */
 declare function build(mode: BuildMode, options: BuildOptions): Promise<Result<BuildResult, Error>>;
 
-export { BuildContext, BuildMode, BuildOptions, BuildResult, InputSpec, LogLevel, ModelSpec, OutputSpec, Plugin, ResolvedConfig, UserConfig, build };
+export { BuildContext, BuildMode, BuildOptions, BuildResult, InputSpec, LogLevel, ModelSpec, OutputSpec, Plugin, ResolvedConfig, ResolvedModelSpec, UserConfig, VarName, build };

package/dist/index.d.ts

@@ -8,10 +8,14 @@ type LogLevel = 'error' | 'info' | 'verbose';
  */
 type BuildMode = 'development' | 'production';
 
+/** A variable name as used in the modeling tool. */
+type VarName = string;
 /**
  * Describes a model input variable.
  */
 interface InputSpec {
+    /** The variable name (as used in the modeling tool). */
+    varName: VarName;
     /**
      * The stable input identifier.  It is recommended to set this to a value (for example, a
      * numeric string like what `plugin-config` uses) that is separate from `varName` and is
@@ -21,33 +25,164 @@ interface InputSpec {
      * note that this approach will be less resilient to renames.
      */
     inputId?: string;
-    /** The variable name (as used in the modeling tool). */
-    varName: string;
     /** The default value for the input. */
-    defaultValue: number;
+    defaultValue?: number;
     /** The minimum value for the input. */
-    minValue: number;
+    minValue?: number;
     /** The maximum value for the input. */
-    maxValue: number;
+    maxValue?: number;
 }
 /**
  * Describes a model output variable.
  */
 interface OutputSpec {
     /** The variable name (as used in the modeling tool). */
-    varName: string;
+    varName: VarName;
 }
 /**
  * Describes a model (e.g., a Vensim mdl file) and the input/output variables
- * that should be included in the model generated by SDE.
+ * that should be included in the model generated by SDEverywhere.
  */
 interface ModelSpec {
-    /** The input variable specs. */
+    /**
+     * The input variables for the model.  This can either be a simple array of
+     * input variable names, or an array of `InputSpec` instances.
+     *
+     * The builder requires only variable names for the purposes of generating
+     * a model, but some plugins may require full `InputSpec` instances.
+     */
+    inputs: VarName[] | InputSpec[];
+    /**
+     * The output variables for the model.  This can either be a simple array of
+     * output variable names, or an array of `OutputSpec` instances.
+     */
+    outputs: VarName[] | OutputSpec[];
+    /**
+     * The dat files that provide the data for exogenous data variables in the
+     * model.
+     */
+    datFiles?: string[];
+    /**
+     * Whether to bundle a model listing with the generated model.
+     *
+     * If undefined, defaults to false.
+     *
+     * When this is true, a model listing will be bundled with the generated
+     * model to allow the `runtime` package to resolve variables that are
+     * referenced by name or identifier.  This listing will increase the size
+     * of the generated model, so it is recommended to set this to true only
+     * if it is needed.
+     */
+    bundleListing?: boolean;
+    /**
+     * Whether to allow lookups to be overridden at runtime using `setLookup`.
+     *
+     * If undefined or false, the generated model will implement `setLookup`
+     * as a no-op, meaning that lookups cannot be overridden at runtime.
+     *
+     * If true, all lookups in the generated model will be available to be
+     * overridden.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be overridden.
+     */
+    customLookups?: boolean | VarName[];
+    /**
+     * Whether to allow for capturing the data for arbitrary variables at
+     * runtime (including variables that are not configured in the `outputs`
+     * array).
+     *
+     * If undefined or false, the generated model will implement `storeOutput`
+     * as a no-op, meaning that the data for arbitrary variables cannot be
+     * captured at runtime.
+     *
+     * If true, all variables in the generated model will be available to be
+     * captured at runtime.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be captured at runtime.
+     */
+    customOutputs?: boolean | VarName[];
+    /** Additional options included with the SDE `spec.json` file. */
+    options?: {
+        [key: string]: any;
+    };
+}
+/**
+ * Describes a model (e.g., a Vensim mdl file) and the input/output variables
+ * that should be included in the model generated by SDEverywhere.  This is
+ * largely the same as the `ModelSpec` interface, except this one has been
+ * fully resolved (paths have been validated, input and output variables have
+ * been checked, etc).  This is the spec object that will be passed to plugin
+ * functions.
+ */
+interface ResolvedModelSpec {
+    /**
+     * The input variable names for the model.  This will be defined regardless
+     * of whether `ModelSpec.inputs` was defined as an array of variable names
+     * or an array of `InputSpec` instances.  (The input variable names are
+     * derived from the `InputSpec` instances as needed.)
+     */
+    inputVarNames: VarName[];
+    /**
+     * The input variable specs for the model.
+     */
     inputs: InputSpec[];
-    /** The output variable specs. */
+    /**
+     * The output variable names for the model.  This will be defined regardless
+     * of whether `ModelSpec.outputs` was defined as an array of variable names
+     * or an array of `OutputSpec` instances.  (The output variable names are
+     * derived from the `OutputSpec` instances as needed.)
+     */
+    outputVarNames: VarName[];
+    /**
+     * The output variable specs for the model.
+     */
     outputs: OutputSpec[];
-    /** The dat files to be included with the SDE `spec.json` file. */
+    /**
+     * The dat files that provide the data for exogenous data variables in the
+     * model.
+     */
     datFiles: string[];
+    /**
+     * Whether to bundle a model listing with the generated model.
+     *
+     * When this is true, a model listing will be bundled with the generated
+     * model to allow the `runtime` package to resolve variables that are
+     * referenced by name or identifier.  This listing will increase the size
+     * of the generated model, so it is recommended to set this to true only
+     * if it is needed.
+     */
+    bundleListing: boolean;
+    /**
+     * Whether to allow lookups to be overridden at runtime using `setLookup`.
+     *
+     * If false, the generated model will contain a `setLookup` function that
+     * throws an error, meaning that lookups cannot be overridden at runtime.
+     *
+     * If true, all lookups in the generated model will be available to be
+     * overridden.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be overridden.
+     */
+    customLookups: boolean | VarName[];
+    /**
+     * Whether to allow for capturing the data for arbitrary variables at
+     * runtime (including variables that are not configured in the `outputs`
+     * array).
+     *
+     * If false, the generated model will contain a `storeOutput` function
+     * that throws an error, meaning that the data for arbitrary variables
+     * cannot be captured at runtime.
+     *
+     * If true, all variables in the generated model will be available to be
+     * captured at runtime.
+     *
+     * If an array is provided, only those variable names in the array will
+     * be available to be captured at runtime.
+     */
+    customOutputs: boolean | VarName[];
     /** Additional options included with the SDE `spec.json` file. */
     options?: {
         [key: string]: any;
@@ -88,6 +223,17 @@ interface ResolvedConfig {
      * can be paths to files or glob patterns (relative to the project directory).
      */
     watchPaths: string[];
+    /**
+     * The code format to generate.  If 'js', the model will be compiled to a JavaScript
+     * file.  If 'c', the model will be compiled to a C file (in which case an additional
+     * plugin will be needed to convert the C code to a WebAssembly module).
+     */
+    genFormat: 'js' | 'c';
+    /**
+     * The absolute path to the JSON file that will be written by the build process that
+     * lists all dimensions and variables in the model.
+     */
+    outListingFile?: string;
     /**
      * The path to the `@sdeverywhere/cli` package.  This is currently only used to get
      * access to the files in the `src/c` directory.
@@ -272,8 +418,8 @@ declare class BuildContext {
  *   - preGenerate
  *       - preProcessMdl
  *       - postProcessMdl
- *       - preGenerateC
- *       - postGenerateC
+ *       - preGenerateCode
+ *       - postGenerateCode
  *   - postGenerate
  *   - postBuild
  *   - watch (only called once after initial build steps when mode==development)
@@ -292,7 +438,7 @@ interface Plugin {
      * @param context The build context (for logging, etc).
      * @param modelSpec The spec that controls how the model is generated.
      */
-    preGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<void>;
+    preGenerate?(context: BuildContext, modelSpec: ResolvedModelSpec): Promise<void>;
     /**
      * Called before SDE preprocesses the mdl file (in the case of one mdl file),
      * or before SDE flattens the mdl files (in the case of multiple mdl files).
@@ -310,19 +456,21 @@ interface Plugin {
      */
     postProcessMdl?(context: BuildContext, mdlContent: string): Promise<string>;
     /**
-     * Called before SDE generates a C file from the mdl file.
+     * Called before SDE generates a JS or C file from the mdl file.
      *
      * @param context The build context (for logging, etc).
+     * @param format The generated code format, either 'js' or 'c'.
      */
-    preGenerateC?(context: BuildContext): Promise<void>;
+    preGenerateCode?(context: BuildContext, format: 'js' | 'c'): Promise<void>;
     /**
-     * Called after SDE generates a C file from the mdl file.
+     * Called after SDE generates a JS or C file from the mdl file.
      *
      * @param context The build context (for logging, etc).
-     * @param cContent The resulting C file content.
-     * @return The modified C file content (if postprocessing was needed).
+     * @param format The generated code format, either 'js' or 'c'.
+     * @param content The resulting JS or C file content.
+     * @return The modified JS or C file content (if postprocessing was needed).
      */
-    postGenerateC?(context: BuildContext, cContent: string): Promise<string>;
+    postGenerateCode?(context: BuildContext, format: 'js' | 'c', content: string): Promise<string>;
     /**
      * Called after the "generate model" process has completed (but before the staged
      * files are copied to their destination).
@@ -332,7 +480,7 @@ interface Plugin {
      * @return Whether the plugin succeeded (for example, a plugin that runs tests can
      * return false to indicate that one or more tests failed).
      */
-    postGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<boolean>;
+    postGenerate?(context: BuildContext, modelSpec: ResolvedModelSpec): Promise<boolean>;
     /**
      * Called after the model has been generated and after the staged files
      * have been copied to their destination.
@@ -342,7 +490,7 @@ interface Plugin {
      * @return Whether the plugin succeeded (for example, a plugin that runs tests can
      * return false to indicate that one or more tests failed).
      */
-    postBuild?(context: BuildContext, modelSpec: ModelSpec): Promise<boolean>;
+    postBuild?(context: BuildContext, modelSpec: ResolvedModelSpec): Promise<boolean>;
     /**
      * Called in development/watch mode after the initial build has completed
      * (i.e., after the model has been generated and after the staged files
@@ -384,6 +532,19 @@ interface UserConfig {
      * If left undefined, this will resolve to the `modelFiles` array.
      */
     watchPaths?: string[];
+    /**
+     * The code format to generate.  If 'js', the model will be compiled to a JavaScript
+     * file.  If 'c', the model will be compiled to a C file (in which case an additional
+     * plugin will be needed to convert the C code to a WebAssembly module).  If undefined,
+     * defaults to 'js'.
+     */
+    genFormat?: 'js' | 'c';
+    /**
+     * If defined, the build process will write a JSON file to the provided path that lists
+     * all dimensions and variables in the model.  This can be an absolute path, or if it
+     * is a relative path it will be resolved relative to the `rootDir` for the project.
+     */
+    outListingFile?: string;
     /**
      * The array of plugins that are used to customize the build process.  These will be
      * executed in the order defined here.
@@ -437,4 +598,4 @@ interface BuildResult {
  */
 declare function build(mode: BuildMode, options: BuildOptions): Promise<Result<BuildResult, Error>>;
 
-export { BuildContext, BuildMode, BuildOptions, BuildResult, InputSpec, LogLevel, ModelSpec, OutputSpec, Plugin, ResolvedConfig, UserConfig, build };
+export { BuildContext, BuildMode, BuildOptions, BuildResult, InputSpec, LogLevel, ModelSpec, OutputSpec, Plugin, ResolvedConfig, ResolvedModelSpec, UserConfig, VarName, build };