feat: change ModelSpec to allow for simple array of input/output var …

…names (#495)

Fixes #494

examples/hello-world/sde.config.js

@@ -8,8 +8,7 @@ export async function config() {
     modelSpec: async () => {
       return {
         inputs: [{ varName: 'Y', defaultValue: 0, minValue: -10, maxValue: 10 }],
-        outputs: [{ varName: 'Z' }],
-        datFiles: []
+        outputs: [{ varName: 'Z' }]
       }
     },
 

examples/house-game/sde.config.js

@@ -1,4 +1,3 @@
-import { copyFile } from 'fs/promises'
 import { dirname, join as joinPath } from 'path'
 import { fileURLToPath } from 'url'
 
@@ -10,21 +9,6 @@ const packagePath = (...parts) => joinPath(__dirname, 'packages', ...parts)
 const appPath = (...parts) => packagePath('app', ...parts)
 const generatedFilePath = (...parts) => appPath('src', 'model', 'generated', ...parts)
 
-function input(varName, defaultValue) {
-  return {
-    varName,
-    defaultValue,
-    minValue: defaultValue,
-    maxValue: defaultValue
-  }
-}
-
-function output(varName) {
-  return {
-    varName
-  }
-}
-
 export async function config() {
   return {
     // Specify the Vensim model to read
@@ -34,13 +18,13 @@ export async function config() {
     modelSpec: async () => {
       return {
         inputs: [
-          input('additional houses required value', 0),
-          input('average house life', 0),
-          input('time to plan to build', 3),
-          input('time to build houses', 6),
-          input('time to respond to gap', 8)
+          'additional houses required value',
+          'average house life',
+          'time to plan to build',
+          'time to build houses',
+          'time to respond to gap'
         ],
-        outputs: [output('number of houses required'), output('houses completed')],
+        outputs: ['number of houses required', 'houses completed'],
         datFiles: ['../model/houses.dat']
       }
     },

packages/build/docs/index.md

@@ -16,8 +16,7 @@ export async function config() {
     modelSpec: async () => {
       return {
         inputs: [{ varName: 'Y', defaultValue: 0, minValue: -10, maxValue: 10 }],
-        outputs: [{ varName: 'Z' }],
-        datFiles: []
+        outputs: [{ varName: 'Z' }]
       }
     }
   }
@@ -41,3 +40,4 @@ export async function config() {
 - [Plugin](interfaces/Plugin.md)
 - [BuildContext](classes/BuildContext.md)
 - [ResolvedConfig](interfaces/ResolvedConfig.md)
+- [ResolvedModelSpec](interfaces/ResolvedModelSpec.md)

packages/build/docs/interfaces/InputSpec.md

@@ -6,6 +6,14 @@ Describes a model input variable.
 
 ## Properties
 
+### varName
+
+ **varName**: `string`
+
+The variable name (as used in the modeling tool).
+
+___
+
 ### inputId
 
  `Optional` **inputId**: `string`
@@ -19,32 +27,24 @@ note that this approach will be less resilient to renames.
 
 ___
 
-### varName
-
- **varName**: `string`
-
-The variable name (as used in the modeling tool).
-
-___
-
 ### defaultValue
 
- **defaultValue**: `number`
+ `Optional` **defaultValue**: `number`
 
 The default value for the input.
 
 ___
 
 ### minValue
 
- **minValue**: `number`
+ `Optional` **minValue**: `number`
 
 The minimum value for the input.
 
 ___
 
 ### maxValue
 
- **maxValue**: `number`
+ `Optional` **maxValue**: `number`
 
 The maximum value for the input.

packages/build/docs/interfaces/ModelSpec.md

@@ -3,31 +3,37 @@
 # Interface: ModelSpec
 
 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.
 
 ## Properties
 
 ### inputs
 
- **inputs**: [`InputSpec`](InputSpec.md)[]
+ **inputs**: `string`[] \| [`InputSpec`](InputSpec.md)[]
 
-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.
 
 ___
 
 ### outputs
 
- **outputs**: [`OutputSpec`](OutputSpec.md)[]
+ **outputs**: `string`[] \| [`OutputSpec`](OutputSpec.md)[]
 
-The output variable specs.
+The output variables for the model.  This can either be a simple array of
+output variable names, or an array of `OutputSpec` instances.
 
 ___
 
 ### datFiles
 
- **datFiles**: `string`[]
+ `Optional` **datFiles**: `string`[]
 
-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.
 
 ___
 

packages/build/docs/interfaces/Plugin.md

@@ -51,7 +51,7 @@ Called before the "generate model" steps are performed.
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `context` | [`BuildContext`](../classes/BuildContext.md) | The build context (for logging, etc). |
-| `modelSpec` | [`ModelSpec`](ModelSpec.md) | The spec that controls how the model is generated. |
+| `modelSpec` | [`ResolvedModelSpec`](ResolvedModelSpec.md) | The spec that controls how the model is generated. |
 
 #### Returns
 
@@ -153,7 +153,7 @@ files are copied to their destination).
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `context` | [`BuildContext`](../classes/BuildContext.md) | The build context (for logging, etc). |
-| `modelSpec` | [`ModelSpec`](ModelSpec.md) | The spec that controls how the model is generated. |
+| `modelSpec` | [`ResolvedModelSpec`](ResolvedModelSpec.md) | The spec that controls how the model is generated. |
 
 #### Returns
 
@@ -176,7 +176,7 @@ have been copied to their destination.
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `context` | [`BuildContext`](../classes/BuildContext.md) | The build context (for logging, etc). |
-| `modelSpec` | [`ModelSpec`](ModelSpec.md) | The spec that controls how the model is generated. |
+| `modelSpec` | [`ResolvedModelSpec`](ResolvedModelSpec.md) | The spec that controls how the model is generated. |
 
 #### Returns
 

packages/build/docs/interfaces/ResolvedModelSpec.md

@@ -0,0 +1,69 @@
+[@sdeverywhere/build](../index.md) / ResolvedModelSpec
+
+# Interface: ResolvedModelSpec
+
+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.
+
+## Properties
+
+### inputVarNames
+
+ **inputVarNames**: `string`[]
+
+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.)
+
+___
+
+### inputs
+
+ **inputs**: [`InputSpec`](InputSpec.md)[]
+
+The input variable specs for the model.
+
+___
+
+### outputVarNames
+
+ **outputVarNames**: `string`[]
+
+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.)
+
+___
+
+### outputs
+
+ **outputs**: [`OutputSpec`](OutputSpec.md)[]
+
+The output variable specs for the model.
+
+___
+
+### datFiles
+
+ **datFiles**: `string`[]
+
+The dat files that provide the data for exogenous data variables in the
+model.
+
+___
+
+### options
+
+ `Optional` **options**: `Object`
+
+Additional options included with the SDE `spec.json` file.
+
+#### Index signature
+
+▪ [key: `string`]: `any`

packages/build/docs/types/VarName.md

@@ -0,0 +1,7 @@
+[@sdeverywhere/build](../index.md) / VarName
+
+# Type alias: VarName
+
+ **VarName**: `string`
+
+A variable name as used in the modeling tool.

packages/build/src/_shared/model-spec.ts

@@ -1,9 +1,15 @@
 // Copyright (c) 2022 Climate Interactive / New Venture Fund
 
+/** A variable name as used in the modeling tool. */
+export type VarName = string
+
 /**
  * Describes a model input variable.
  */
 export 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
@@ -14,40 +20,95 @@ export interface InputSpec {
    */
   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.
  */
 export 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.
  */
 export 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[]
+
+  /** Additional options included with the SDE `spec.json` file. */
+  // TODO: Remove references to `spec.json`
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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.
+ */
+export 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. */
-  // TODO: Remove references to `spec.json`
+  /**
+   * The dat files that provide the data for exogenous data variables in the
+   * model.
+   */
   datFiles: string[]
 
   /** Additional options included with the SDE `spec.json` file. */