add docs publish task to CI

.github/workflows/docs-publish.yaml

@@ -0,0 +1,34 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: 19.9.0
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        run: npm run docs
+
+      - name: Generate TypeDocs
+        run: npm run docs
+
+      - name: Deploy TypeDocs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs

package.json

@@ -21,11 +21,12 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "tsc && npm run webpack",
+    "build": "tsc && npm run webpack && npm run docs",
     "webpack": "webpack && webpack --config webpack.config.cjs.js",
     "test": "npm run clean && npm run build && node --experimental-vm-modules node_modules/jest/bin/jest.js --detectOpenHandles",
     "test-fast": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "stated": "node --experimental-vm-modules dist/stated.js"
+    "stated": "node --experimental-vm-modules dist/stated.js",
+    "docs": "typedoc --out docs src/*"
   },
   "bin": {
     "stated": "./dist/stated.js"
@@ -65,7 +66,7 @@
     "copy-webpack-plugin": "^11.0.0",
     "jest": "^29.7.0",
     "path-browserify": "^1.0.1",
-    "typedoc": "^0.25.1",
+    "typedoc": "^0.25.7",
     "typescript": "^5.2.2",
     "webpack": "^5.88.2",
     "webpack-cli": "^5.1.4"

src/TemplateProcessor.ts

@@ -38,6 +38,111 @@ export type StatedError = {
     };
 };
 
+/**
+ * This is the main TemplateProcessor class.
+ *
+ * @remarks
+ * The TemplateProcessor class is responsible for processing templates and interfacing with your program that may
+ * provide changing inputs over time and react to changes with callbacks. Many examples can be found in
+ * `src/test/TemplateProcessor.test.js`
+ *
+ * @example Initialize a simple template stored in local object 'o'
+ * ```
+ * //initialize a simple template stored in local object 'o'
+ * test("test 6", async () => {
+ *     const o = {
+ *         "a": 10,
+ *         "b": [
+ *             "../${a}",
+ *         ]
+ *     };
+ *     const tp = new TemplateProcessor(o);
+ *     await tp.initialize();
+ *     expect(o).toEqual({
+ *         "a": 10,
+ *         "b": [10]
+ *     });
+ * });
+ * ```
+ * @example Pass the TemplateProcessor a context containing a function named `nozzle` and a variable named `ZOINK`
+ * ```
+ * //Pass the TemplateProcessor a context containing a function named `nozzle` and a variable named `ZOINK`
+ * test("context", async () => {
+ *     const nozzle = (something) => "nozzle got some " + something;
+ *     const context = {"nozzle": nozzle, "ZOINK": "ZOINK"}
+ *     const tp = new TemplateProcessor({
+ *         "a": "${$nozzle($ZOINK)}"
+ *     }, context);
+ *     await tp.initialize();
+ *     expect(tp.output).toEqual(
+ *         {
+ *             "a": "nozzle got some ZOINK",
+ *         }
+ *     );
+ * });
+ * ```
+ * @example Parse template from JSON or YAML
+ * ```
+ *     it('should correctly identify and parse JSON string', async () => {
+ *         const jsonString = '{"key": "value"}';
+ *         const instance = TemplateProcessor.fromString(jsonString);
+ *         await instance.initialize();
+ *         expect(instance).toBeInstanceOf(TemplateProcessor);
+ *         expect(instance.output).toEqual({ key: "value" });  // Assuming parsedObject is publicly accessible
+ *     });
+ *
+ *     it('should correctly identify and parse YAML string using ---', async () => {
+ *         const yamlString = `---
+ * key: value`;
+ *         const instance = TemplateProcessor.fromString(yamlString);
+ *         await instance.initialize();
+ *         expect(instance).toBeInstanceOf(TemplateProcessor);
+ *         expect(instance.output).toEqual({ key: "value" });
+ *     });
+ *  ```
+ *  @example React to changes using data change callbacks on various locations in the template
+ *  ```
+ *  test("test 1", async () => {
+ *     const tp = new TemplateProcessor({
+ *         "a": "aaa",
+ *         "b": "${a}"
+ *     });
+ *     await tp.initialize();
+ *     const received = [];
+ *     tp.setDataChangeCallback("/a", (data, jsonPtr) => {
+ *         received.push({data, jsonPtr})
+ *     });
+ *     tp.setDataChangeCallback("/b", (data, jsonPtr) => {
+ *         received.push({data, jsonPtr})
+ *     });
+ *     tp.setDataChangeCallback("/", (data, jsonPtr) => {
+ *         received.push({data, jsonPtr})
+ *     });
+ *     await tp.setData("/a", 42);
+ *     expect(received).toEqual([
+ *         {
+ *             "data": 42,
+ *             "jsonPtr": "/a"
+ *         },
+ *         {
+ *             "data": 42,
+ *             "jsonPtr": "/b"
+ *         },
+ *         {
+ *             "data": {
+ *                 "a": 42,
+ *                 "b": 42
+ *             },
+ *             "jsonPtr": [
+ *                 "/a",
+ *                 "/b"
+ *             ]
+ *         }
+ *     ]);
+ * });
+ * ```
+ */
+
 export default class TemplateProcessor {
     /**
      * Loads a template and initializes a new template processor instance.

src/test/TemplateProcessor.test.js

@@ -1432,37 +1432,41 @@ test("ex14.yaml", async () => {
 });
 describe('TemplateProcessor.fromString', () => {
 
-    it('should correctly identify and parse JSON string', () => {
+    it('should correctly identify and parse JSON string', async () => {
         const jsonString = '{"key": "value"}';
         const instance = TemplateProcessor.fromString(jsonString);
+        await instance.initialize();
         expect(instance).toBeInstanceOf(TemplateProcessor);
         expect(instance.output).toEqual({ key: "value" });  // Assuming parsedObject is publicly accessible
     });
 
-    it('should correctly identify and parse YAML string using ---', () => {
+    it('should correctly identify and parse YAML string using ---', async () => {
         const yamlString = `---
 key: value`;
         const instance = TemplateProcessor.fromString(yamlString);
+        await instance.initialize();
         expect(instance).toBeInstanceOf(TemplateProcessor);
         expect(instance.output).toEqual({ key: "value" });
     });
 
-    it('should correctly identify and parse YAML string using colon', () => {
+    it('should correctly identify and parse YAML string using colon', async () => {
         const yamlString = `key: value`;
         const instance = TemplateProcessor.fromString(yamlString);
+        await instance.initialize();
         expect(instance).toBeInstanceOf(TemplateProcessor);
         expect(instance.output).toEqual({ key: "value" });
     });
 
-    it('should throw an error for unknown formats', () => {
+    it('should throw an error for unknown formats', async () => {
         const unknownString = `Hello World`;
         expect(() => TemplateProcessor.fromString(unknownString)).toThrow("Unknown format");
     });
 
-    it('should not misinterpret colon in JSON string', () => {
+    it('should not misinterpret colon in JSON string', async () => {
         const jsonString = '{"greeting": "Hello: World"}';
         const instance = TemplateProcessor.fromString(jsonString);
         expect(instance).toBeInstanceOf(TemplateProcessor);
+        await instance.initialize();
         expect(instance.output).toEqual({ greeting: "Hello: World" });
     });
 

yarn.lock

@@ -2963,9 +2963,9 @@ jsonata@^2.0.3:
   integrity sha512-Up2H81MUtjqI/dWwWX7p4+bUMfMrQJVMN/jW6clFMTiYP528fBOBNtRu944QhKTs3+IsVWbgMeUTny5fw2VMUA==
 
 jsonc-parser@^3.2.0:
-  version "3.2.0"
-  resolved "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz"
-  integrity sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==
+  version "3.2.1"
+  resolved "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.1.tgz"
+  integrity sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==
 
 kind-of@^6.0.2:
   version "6.0.3"
@@ -3542,10 +3542,10 @@ shebang-regex@^3.0.0:
   resolved "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz"
   integrity sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==
 
-shiki@^0.14.1:
-  version "0.14.4"
-  resolved "https://registry.npmjs.org/shiki/-/shiki-0.14.4.tgz"
-  integrity sha512-IXCRip2IQzKwxArNNq1S+On4KPML3Yyn8Zzs/xRgcgOWIr8ntIK3IKzjFPfjy/7kt9ZMjc+FItfqHRBg8b6tNQ==
+shiki@^0.14.7:
+  version "0.14.7"
+  resolved "https://registry.npmjs.org/shiki/-/shiki-0.14.7.tgz"
+  integrity sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==
   dependencies:
     ansi-sequence-parser "^1.1.0"
     jsonc-parser "^3.2.0"
@@ -3766,17 +3766,17 @@ type-fest@^0.21.3:
   resolved "https://registry.npmjs.org/type-fest/-/type-fest-0.21.3.tgz"
   integrity sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==
 
-typedoc@^0.25.1:
-  version "0.25.1"
-  resolved "https://registry.npmjs.org/typedoc/-/typedoc-0.25.1.tgz"
-  integrity sha512-c2ye3YUtGIadxN2O6YwPEXgrZcvhlZ6HlhWZ8jQRNzwLPn2ylhdGqdR8HbyDRyALP8J6lmSANILCkkIdNPFxqA==
+typedoc@^0.25.7:
+  version "0.25.7"
+  resolved "https://registry.npmjs.org/typedoc/-/typedoc-0.25.7.tgz"
+  integrity sha512-m6A6JjQRg39p2ZVRIN3NKXgrN8vzlHhOS+r9ymUYtcUP/TIQPvWSq7YgE5ZjASfv5Vd5BW5xrir6Gm2XNNcOow==
   dependencies:
     lunr "^2.3.9"
     marked "^4.3.0"
     minimatch "^9.0.3"
-    shiki "^0.14.1"
+    shiki "^0.14.7"
 
-typescript@^5.2.2, "[email protected] || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x":
+typescript@^5.2.2, "[email protected] || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x":
   version "5.2.2"
   resolved "https://registry.npmjs.org/typescript/-/typescript-5.2.2.tgz"
   integrity sha512-mI4WrpHsbCIcwT9cF4FZvr80QUeKvsUsUvKDoR+X/7XHQH98xYD8YHZg7ANtz2GtZt/CBq2QJ0thkGJMHfqc1w==