@jamesgmarks/sandbox v0.1.5
Sandbox
Basic Usage
- Install:
npm i @jamesgmarks/sandbox
oryarn add @jamesgmarks/sandbox
- Add
sandbox.*.dev.ts
to your.gitignore
list. - Create a folder in your project and set your
SANDBOX_DIRECTORY
environment var to point to that folder. - Optionally hook your application into a router and/or UI. (See API below)
- 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.
- Run your sandboxes. Using the API (or your own hooked in UI), run sandboxes to perform tests.
Conventions
Filename: When creating your files, name them
sandbox.your_snakecase_name.dev.ts
. Replaceyour_snakecase_name
with whatever you want to name this file as long as it is written in snake case. Leave thesandbox.
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.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 beMySandbox
and for the example below the filename would besandbox.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.