improve API for YAML custom tags

Author: stevensJourney

.changeset/bright-gifts-turn.md

@@ -4,4 +4,20 @@
 
 - Added `ServiceContextMode` to `ServiceContext`. This conveys the mode in which the PowerSync service was started in.
 - `RouterEngine` is now always present on `ServiceContext`. The router will only configure actual servers, when started, if routes have been registered.
-- Added `!env_boolean` and `!env_number` YAML tag functions to `CompoundConfigCollector`.
+- Added typecasting to `!env` YAML custom tag function. YAML config environment variable substitution now support casting string environment variables to `number` and `boolean` types.
+
+```yaml
+replication:
+  connections: []
+
+storage:
+  type: mongodb
+
+api:
+  parameters:
+    max_buckets_per_connection: !env PS_MAX_BUCKETS::number
+
+healthcheck:
+  probes:
+    use_http: !env PS_MONGO_HEALTHCHECK::boolean
+```

.changeset/khaki-cows-thank.md

@@ -2,16 +2,22 @@
 '@powersync/service-image': minor
 ---
 
-- Added type casting for YAML tag functions. YAML config can now substitute environment variables as boolean and number types.
+- Added typecasting to `!env` YAML custom tag function. YAML config environment variable substitution now support casting string environment variables to `number` and `boolean` types.
 
 ```yaml
-# PowerSync config
+replication:
+  connections: []
+
+storage:
+  type: mongodb
+
 api:
   parameters:
-    max_buckets_per_connection: !env_number PS_MAX_BUCKETS
+    max_buckets_per_connection: !env PS_MAX_BUCKETS::number
+
 healthcheck:
   probes:
-    http: !env_boolean PS_MONGO_HEALTHCHECK
+    use_http: !env PS_MONGO_HEALTHCHECK::boolean
 ```
 
 - Added the ability to customize healthcheck probe exposure in the configuration. Backwards compatibility is maintained if no `healthcheck->probes` config is provided.
@@ -20,7 +26,7 @@ healthcheck:
 healthcheck:
   probes:
     # Health status can be accessed by reading files (previously always enabled)
-    filesystem: true
+    use_filesystem: true
     # Health status can be accessed via HTTP requests (previously enabled for API and UNIFIED service modes)
-    http: true
+    use_http: true
 ```

packages/service-core/src/util/config/collectors/config-collector.ts

@@ -4,7 +4,7 @@ import { configFile } from '@powersync/service-types';
 
 import { schema } from '@powersync/lib-services-framework';
 import { RunnerConfig } from '../types.js';
-import { YamlEnvTag, YamlEnvTagBoolean, YamlEnvTagNumber } from './impl/yaml-env.js';
+import { YamlEnvTag } from './impl/yaml-env.js';
 
 export enum ConfigFileFormat {
   YAML = 'yaml',
@@ -89,7 +89,7 @@ export abstract class ConfigCollector {
       schema: 'core',
       keepSourceTokens: true,
       lineCounter,
-      customTags: [YamlEnvTag, YamlEnvTagBoolean, YamlEnvTagNumber]
+      customTags: [YamlEnvTag]
     });
 
     if (parsed.errors.length) {

packages/service-core/src/util/config/collectors/impl/yaml-env.ts

@@ -14,77 +14,54 @@ const YAML_ENV_PREFIX = 'PS_';
 
 /**
  * Custom YAML tag which performs string environment variable substitution
+ * Allows for type casting string environment variables to boolean or number
+ * by using the syntax !env PS_MONGO_PORT::number or !env PS_USE_SUPABASE::boolean
  */
 export const YamlEnvTag: yaml.ScalarTag = {
   tag: '!env',
-  resolve(envName: string, onError: (error: string) => void): string {
+  resolve(envName: string, onError: (error: string) => void) {
     if (!envName.startsWith(YAML_ENV_PREFIX)) {
       onError(
         `Attempting to substitute environment variable ${envName} is not allowed. Variables must start with "${YAML_ENV_PREFIX}"`
       );
       return envName;
     }
-    const value = process.env[envName];
+
+    // allow type casting if the envName contains a type suffix
+    // e.g. PS_MONGO_PORT::number or PS_USE_SUPABASE::boolean
+    const [name, type = 'string'] = envName.split('::');
+
+    let value = process.env[name];
+
     if (typeof value == 'undefined') {
       onError(
         `Attempted to substitute environment variable "${envName}" which is undefined. Set this variable on the environment.`
       );
       return envName;
     }
-    return value;
-  }
-};
 
-/**
- * Casts the environment variable to a boolean.
- */
-export const YamlEnvTagBoolean: yaml.ScalarTag = {
-  tag: '!env_boolean',
-  resolve(envName: string, onError: (error: string) => void) {
-    const stringValue = YamlEnvTag.resolve(envName, onError, {});
-    if (stringValue == envName) {
-      // This is returned for error conditions
-      return stringValue;
+    switch (type) {
+      case 'string':
+        return value;
+      case 'number':
+        const numberValue = Number(value);
+        if (Number.isNaN(numberValue)) {
+          onError(`Environment variable "${envName}" is not a valid number. Got: "${value}".`);
+          return envName;
+        }
+        return numberValue;
+      case 'boolean':
+        if (value?.toLowerCase() == 'true') {
+          return true;
+        } else if (value?.toLowerCase() == 'false') {
+          return false;
+        } else {
+          onError(`Environment variable "${envName}" is not a boolean. Expected "true" or "false", got "${value}".`);
+          return envName;
+        }
+      default:
+        onError(`Environment variable "${envName}" has an invalid type suffix "${type}".`);
+        return envName;
     }
-    if (typeof stringValue !== 'string') {
-      // should not reach this point
-      onError(`Environment variable "${envName}" is not a string.`);
-      return stringValue;
-    }
-    if (stringValue.toLowerCase() == 'true') {
-      return true;
-    } else if (stringValue.toLowerCase() == 'false') {
-      return false;
-    } else {
-      onError(`Environment variable "${envName}" is not a boolean. Expected "true" or "false", got "${stringValue}".`);
-      return stringValue;
-    }
-  }
-};
-
-/**
- * Casts the environment variable to a number.
- */
-export const YamlEnvTagNumber: yaml.ScalarTag = {
-  tag: '!env_number',
-  resolve(envName: string, onError: (error: string) => void) {
-    const stringValue = YamlEnvTag.resolve(envName, onError, {});
-    if (stringValue == envName) {
-      // This is returned for error conditions from YamlEnvTag
-      return stringValue;
-    }
-
-    if (typeof stringValue !== 'string') {
-      onError(`Environment variable "${envName}" is not a string.`);
-      return stringValue;
-    }
-
-    const numberValue = Number(stringValue);
-    if (Number.isNaN(numberValue)) {
-      onError(`Environment variable "${envName}" is not a valid number. Got: "${stringValue}".`);
-      return stringValue;
-    }
-
-    return numberValue;
   }
 };

packages/service-core/test/src/config.test.ts

@@ -35,7 +35,7 @@ describe('Config', () => {
         type: mongodb
       healthcheck:
         probes:
-          http: !env_boolean PS_MONGO_HEALTHCHECK
+          use_http: !env PS_MONGO_HEALTHCHECK::boolean
     `;
 
     const collector = new CompoundConfigCollector();
@@ -58,7 +58,7 @@ describe('Config', () => {
         type: mongodb
       api:
         parameters:
-          max_buckets_per_connection: !env_number PS_MAX_BUCKETS
+          max_buckets_per_connection: !env PS_MAX_BUCKETS::number
     `;
 
     const collector = new CompoundConfigCollector();