Sandbox

Basic Usage

1. Install: npm i @jamesgmarks/sandbox or yarn add @jamesgmarks/sandbox
2. Add sandbox.*.dev.ts to your .gitignore list.
3. Create a folder in your project and set your SANDBOX_DIRECTORY environment var to point to that folder.
4. Optionally hook your application into a router and/or UI. (See API below)
5. Start creating sandbox files using the provided templates and conventions. Within your application you can access all of the same functionality any other source file in your project can access.
6. Run your sandboxes. Using the API (or your own hooked in UI), run sandboxes to perform tests.

Conventions

1. Filename: When creating your files, name them sandbox.your_snakecase_name.dev.ts. Replace your_snakecase_name with whatever you want to name this file as long as it is written in snake case. Leave the sandbox. prefix and the .dev.ts suffix intact. The name of the file dictate the name of the class inside it, so use something that works for both filename and class name.

2. Template: In your file write a class using the template below. Replace the classname with a PascalCase version of the file name portion you chose for the filename. For example, if your filename was sandbox.my_sandbox.dev.ts, your class name must be MySandbox and for the example below the filename would be sandbox.template.dev.ts.

  /* eslint-disable class-methods-use-this */
  import { Hash, HashOf } from '@jamesgmarks/utilities';
  import { IFieldDescription, Sandbox } from '../Sandbox';

  // this class name must match the file name between "sandbox." and ".dev.php"
  export class Template extends Sandbox {
    // set this to `true` to activate the script
    public active = false;

    public getFields() {
      // Use the following settings to get options for sandbox scripts.
      // See the IFieldDescription interface to see what else you can do with these.
      return {
        text: { type: 'string' }, // Text box
        yesno: { type: 'boolean' }, // Checkbox
        number: { type: 'int' }, // 'int', 'float'
        dropdown: {
          type: 'multiselect',
          options: { key: 'value' },
        },
      } as HashOf<IFieldDescription>;
    }

    public async run(options: Hash = {}) {
      // Do whatever you want here. This is entirely up to you.
      // Typically the return value is used by your implementation of a Sandbox UI
      return {
        Hello: 'Sandbox',
        options,
      };
    }
  }

API

Most available functionality retrieves information about existing sandbox files.

getSandboxDirPath

• Returns the path where sandbox files are expected to be. This should be set with the SANDBOX_DIRECTORY environment variable. (Tip: You are free to set this var in code using process.env) getSandboxFiles
• Returns a list of filenames found in the sandbox directory. getSandboxClasses
• Returns a list of class names in the sandbox files. (string[]) getSandboxFields
• Returns a list of defined fields from a specific sandbox's getFields method. getSandboxBreakdown
• Returns a list of all sandboxes including each sandbox name (snake case) along with its associated fields.

There is one function that is used to execute a sandbox.

runSandbox

• Provide a sandbox name and an object literal containing all required and any optional parameters to execute a sandbox. This method will return the same value that would be returned by the sandbox itself.