[JS] Add getOptions method with schema validation (#177)

JS:
* Add `getOptions<T>` to `OptionsProvider` and `OptionsWatcher`
* Fix `CI with sudo pkg install -y -f ca_root_nss`

Author: juharris

.github/workflows/JS_build_test_publish.yml

@@ -179,7 +179,6 @@ jobs:
           path: ./js/optify-config/${{ env.APP_NAME }}.*.node
           if-no-files-found: error
   build-freebsd:
-    # Disabled for now because it gives too many installation errors such as when trying to install `yarn`.
     if: github.event.pull_request.draft == false || github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     name: "[FreeBSD] Build"
@@ -210,7 +209,8 @@ jobs:
             set -ex
 
             cd js/optify-config
-            sudo pkg install -y -f curl node libnghttp2 npm
+            # ca_root_nss: Helps with downloading Rust toolchains and Node.js binaries.
+            sudo pkg install -y -f ca_root_nss curl node libnghttp2 npm
             sudo npm install -g yarn --ignore-scripts
             curl https://sh.rustup.rs -sSf --output rustup.sh
             sh rustup.sh -y --profile minimal --default-toolchain stable

js/optify-config/README.md

@@ -5,6 +5,41 @@ See the [homepage] for details about how feature files are combined to build the
 
 # Usage
 
+```TypeScript
+import { z } from 'zod'
+import { OptionsProvider } from '@optify/config'
+
+const MyConfigSchema = z.object({
+  rootString: z.string(),
+  myArray: z.array(z.string()),
+  myObject: z.object({
+    key: z.string(),
+    deeper: z.object({
+      new: z.string(),
+      num: z.number(),
+    }),
+  }),
+})
+
+const provider = OptionsProvider.build('<configs folder path>')
+const config = provider.getOptions('myConfig', ['feature_A', 'feature_B'], MyConfigSchema)
+// config is typed and validated at runtime
+console.log(config.rootString)
+console.log(config.myObject.deeper.num)
+```
+
+The `getOptions` method accepts any object with a `parse(data: unknown): T` method, making it compatible with [Zod](https://zod.dev/) and other schema validation libraries.
+This package does not depend on Zod; it only requires the schema to have a `parse` method.
+If desired, install Zod (or your preferred validation library) separately in your project:
+
+```shell
+npm install zod
+```
+
+### Using `getOptionsJson`
+
+If you don't need schema validation, you can use `getOptionsJson` to get the raw JSON string:
+
 ```TypeScript
 import { OptionsProvider } from '@optify/config'
 
@@ -25,20 +60,18 @@ Outputs:
       "new": "new value",
       "num": 3333
     },
-    "key": "val",
+    "key": "val"
   },
   "rootString": "root string same"
 }
 ```
 
-Multiple directories can be used as well:
+### Multiple directories
 
 ```TypeScript
 import { OptionsProvider } from '@optify/config'
 
 const provider = OptionsProvider.buildFromDirectories(['<configs folder path>', '<another folder path>'])
-const options = JSON.parse(provider.getOptionsJson('myConfig', ['feature_A', 'feature_B']))
-console.log(JSON.stringify(options, null, 2))
 ```
 
 # Development

js/optify-config/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@optify/config",
-	"version": "1.1.7",
+	"version": "1.2.0",
 	"description": "Simplifies **configuration driven development**: getting the right configuration options for a process or request using pre-loaded configurations from files (JSON, YAML, etc.) to manage options for feature flags, experiments, or flights.",
 	"repository": {
 		"type": "git",
@@ -38,7 +38,8 @@
 		"jest": "^29.7.0",
 		"tinybench": "^5.1.0",
 		"ts-jest": "^29.3.4",
-		"typescript": "^5.8.3"
+		"typescript": "^5.8.3",
+		"zod": "^4.3.6"
 	},
 	"engines": {
 		"node": ">= 20"

js/optify-config/src/index.ts

@@ -17,16 +17,25 @@ export {
 export type OptionsProvider = nativeBinding.OptionsProvider;
 export type OptionsWatcher = nativeBinding.OptionsWatcher;
 
+/** Any object with a parse method, compatible with Zod schemas. */
+export interface TypeSchema<T> {
+  parse(data: unknown): T;
+}
+
 // Augment the native class interfaces to include our new method
 declare module '../index' {
   interface OptionsProvider {
     /** Returns a map of all the canonical feature names to their metadata. */
     featuresWithMetadata(): Record<string, OptionsMetadata>;
+    /** Gets options for the specified key and feature names, validated against a schema. */
+    getOptions<T>(key: string, featureNames: Array<string>, schema: TypeSchema<T>, preferences?: GetOptionsPreferences | null): T;
   }
 
   interface OptionsWatcher {
     /** Returns a map of all the canonical feature names to their metadata. */
     featuresWithMetadata(): Record<string, OptionsMetadata>;
+    /** Gets options for the specified key and feature names, validated against a schema. */
+    getOptions<T>(key: string, featureNames: Array<string>, schema: TypeSchema<T>, preferences?: GetOptionsPreferences | null): T;
   }
 }
 
@@ -44,6 +53,9 @@ export const OptionsProvider = nativeBinding.OptionsProvider;
 
   return this[CACHE_KEY] = this._featuresWithMetadata();
 };
+(OptionsProvider.prototype as any).getOptions = function (this: any, key: string, featureNames: string[], schema: any, preferences?: nativeBinding.GetOptionsPreferences | null): any {
+  return schema.parse(this._getOptions(key, featureNames, preferences));
+};
 
 // Extend OptionsWatcher prototype with extra methods.
 export const OptionsWatcher = nativeBinding.OptionsWatcher;
@@ -56,4 +68,7 @@ export const OptionsWatcher = nativeBinding.OptionsWatcher;
 
   this[CACHE_TIME_KEY] = lastModifiedTime;
   return this[CACHE_KEY] = this._featuresWithMetadata();
+};
+(OptionsWatcher.prototype as any).getOptions = function (this: any, key: string, featureNames: string[], schema: any, preferences?: nativeBinding.GetOptionsPreferences | null): any {
+  return schema.parse(this._getOptions(key, featureNames, preferences));
 };

js/optify-config/src/provider.rs

@@ -117,6 +117,22 @@ impl JsOptionsProvider {
       .ok()
   }
 
+  #[napi(js_name = "_getOptions")]
+  pub fn get_options(
+    &self,
+    key: String,
+    feature_names: Vec<String>,
+    preferences: Option<&JsGetOptionsPreferences>,
+  ) -> napi::Result<serde_json::Value> {
+    let preferences = preferences.map(|p| &p.inner);
+    self
+      .inner
+      .as_ref()
+      .unwrap()
+      .get_options_with_preferences(&key, &feature_names, None, preferences)
+      .map_err(|e| napi::Error::from_reason(e.to_string()))
+  }
+
   #[napi]
   pub fn get_options_json(
     &self,

js/optify-config/src/watcher.rs

@@ -178,6 +178,22 @@ impl JsOptionsWatcher {
       .ok()
   }
 
+  #[napi(js_name = "_getOptions")]
+  pub fn get_options(
+    &self,
+    key: String,
+    feature_names: Vec<String>,
+    preferences: Option<&JsGetOptionsPreferences>,
+  ) -> napi::Result<serde_json::Value> {
+    let preferences = preferences.map(|p| &p.inner);
+    self
+      .inner
+      .as_ref()
+      .unwrap()
+      .get_options_with_preferences(&key, &feature_names, None, preferences)
+      .map_err(|e| napi::Error::from_reason(e.to_string()))
+  }
+
   #[napi]
   pub fn get_options_json(
     &self,

js/optify-config/tests/optify.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from '@jest/globals';
 import fs from 'fs';
 import path from 'path';
+import { z } from 'zod';
 import { GetOptionsPreferences, OptionsProvider, OptionsWatcher } from "../dist/index";
 
 const runSuite = (suitePath: string) => {
@@ -33,6 +34,62 @@ const runSuite = (suitePath: string) => {
   }
 }
 
+const DeeperObjectSchema = z.object({
+  wtv: z.number(),
+  list: z.array(z.number()),
+});
+
+const MyObjectSchema = z.object({
+  one: z.number(),
+  two: z.number(),
+  string: z.string(),
+  deeper: DeeperObjectSchema,
+});
+
+const MyConfigSchema = z.object({
+  rootString: z.string(),
+  rootString2: z.string(),
+  myArray: z.array(z.string()),
+  myObject: MyObjectSchema,
+});
+
+describe('getOptions', () => {
+  const configsPath = path.join(__dirname, '../../../tests/test_suites/simple/configs');
+  const providers = [{
+    name: "OptionsProvider",
+    provider: OptionsProvider.build(configsPath),
+  }, {
+    name: "OptionsWatcher",
+    provider: OptionsWatcher.build(configsPath),
+  }];
+
+  for (const { name, provider } of providers) {
+    test(`${name} validates and returns a typed object with a schema`, () => {
+      const config = provider.getOptions('myConfig', ['A'], MyConfigSchema);
+      expect(config.rootString).toBe('root string same');
+      expect(config.rootString2).toBe('gets overridden');
+      expect(config.myArray).toEqual(['example item 1']);
+      expect(config.myObject.one).toBe(1);
+      expect(config.myObject.deeper.list).toEqual([1, 2]);
+    });
+
+    test(`${name} getOptions with schema matches getOptionsJson`, () => {
+      const preferences = new GetOptionsPreferences();
+      preferences.enableConfigurableStrings();
+      const fromJson = JSON.parse(provider.getOptionsJson('myConfig', ['A'], preferences));
+      const fromGetOptions = provider.getOptions('myConfig', ['A'], MyConfigSchema, preferences);
+      expect(fromGetOptions).toEqual(fromJson);
+    });
+
+    test(`${name} getOptions with schema rejects invalid data`, () => {
+      const StrictSchema = z.object({
+        rootString: z.number(),
+      });
+      expect(() => provider.getOptions('myConfig', ['A'], StrictSchema)).toThrow();
+    });
+  }
+});
+
 const testSuitesDir = path.join(__dirname, '../../../tests/test_suites');
 for (const suite of fs.readdirSync(testSuitesDir)) {
   describe(`Suite: ${suite}`, () => {

js/optify-config/yarn.lock

@@ -1700,6 +1700,7 @@ __metadata:
     tinybench: "npm:^5.1.0"
     ts-jest: "npm:^29.3.4"
     typescript: "npm:^5.8.3"
+    zod: "npm:^4.3.6"
   languageName: unknown
   linkType: soft
 
@@ -4740,3 +4741,10 @@ __metadata:
   checksum: 10c0/dceb44c28578b31641e13695d200d34ec4ab3966a5729814d5445b194933c096b7ced71494ce53a0e8820685d1d010df8b2422e5bf2cdea7e469d97ffbea306f
   languageName: node
   linkType: hard
+
+"zod@npm:^4.3.6":
+  version: 4.3.6
+  resolution: "zod@npm:4.3.6"
+  checksum: 10c0/860d25a81ab41d33aa25f8d0d07b091a04acb426e605f396227a796e9e800c44723ed96d0f53a512b57be3d1520f45bf69c0cb3b378a232a00787a2609625307
+  languageName: node
+  linkType: hard