@powersync/service-sync-rules 0.39.0 → 0.41.0

package/dist/from_yaml.js

@@ -1,9 +1,9 @@
-import { isScalar, LineCounter, parseDocument, Scalar, YAMLMap, YAMLSeq } from 'yaml';
+import { LineCounter, parseDocument, Scalar } from 'yaml';
 import { DEFAULT_BUCKET_PRIORITY, isValidPriority } from './BucketDescription.js';
 import { CompatibilityContext, CompatibilityEdition, CompatibilityOption, TimeValuePrecision } from './compatibility.js';
 import { SyncStreamsCompiler } from './compiler/compiler.js';
 import { SqlRuleError, SyncRulesErrors, YamlError } from './errors.js';
-import { SqlEventDescriptor } from './events/SqlEventDescriptor.js';
+import { PreparedEventDefinition } from './events/CompiledEventSourceQuery.js';
 import { validateSyncRulesSchema } from './json_schema.js';
 import { SqlBucketDescriptor } from './legacy/SqlBucketDescriptor.js';
 import { syncStreamFromSql } from './legacy/streams/from_sql.js';
@@ -12,6 +12,7 @@ import { validateStorageVersion } from './StorageVersion.js';
 import { PrecompiledSyncConfig } from './sync_plan/evaluator/index.js';
 import { TablePattern } from './TablePattern.js';
 import { buildParsedToSourceValueMap, isBlockScalar, isQuotedScalar } from './yaml_scalar_map.js';
+import { documentState } from './yaml_validation.js';
 const ACCEPT_POTENTIALLY_DANGEROUS_QUERIES = Symbol('ACCEPT_POTENTIALLY_DANGEROUS_QUERIES');
 /**
  * Reads `sync_rules.yaml` files containing a sync configuration.
@@ -47,26 +48,44 @@ export class SyncConfigFromYaml {
                 }
             ]
         });
-        if (parsed.errors.length > 0) {
+        const config = this.#parseConfig(parsed);
+        // #parseConfig() should have found all errors in the YAML source. As an additional check, and to ensure our sync
+        // rules schema is up-to-date, also validate with ajv. We do this last because errors found here don't have line
+        // numbers on them.
+        if (!this.#hasFatalError) {
+            const valid = validateSyncRulesSchema(parsed.toJSON());
+            if (!valid) {
+                this.#errors.push(...validateSyncRulesSchema.errors.map((e) => {
+                    return new YamlError(e);
+                }));
+            }
+        }
+        this.#throwOnErrorIfRequested();
+        return config;
+    }
+    #parseConfig(parsed) {
+        const root = documentState(parsed, (e) => this.#errors.push(e)).requireMap('Sync Config must be a YAML map.');
+        if (parsed.errors.length > 0 || root == null) {
             this.#errors.push(...parsed.errors.map((e) => new YamlError(e)));
             this.#throwOnErrorIfRequested();
             // Return an empty sync config instance if we couldn't parse YAML, it doesn't make sense to try parsing the broken
             // structure further.
             return new SqlSyncRules(this.yaml);
         }
+        using rootState = root;
+        using declaredOptions = rootState.get('config')?.requireMap();
         let compatibility;
         let storageVersion;
-        if (parsed.has('config')) {
-            const declaredOptions = parsed.get('config');
+        if (declaredOptions) {
             compatibility = this.#parseCompatibilityOptions(declaredOptions);
             storageVersion = this.#validateStorageVersion(declaredOptions);
             if (compatibility.isEnabled(CompatibilityOption.sqliteExpressionEngine)) {
                 // Evaluating expressions with SQLite requires edition: 3, older systems always use JavaScript.
-                if (compatibility.edition < CompatibilityEdition.SYNC_STREAMS) {
-                    this.#errors.push(this.#yamlError(declaredOptions, 'Enabling unstable_sqlite_expression_engine requires edition: 3'));
+                if (compatibility.edition < CompatibilityEdition.COMPILED_STREAMS) {
+                    declaredOptions.reportError('Enabling unstable_sqlite_expression_engine requires edition: 3');
                 }
                 else if (!compatibility.isEnabled(CompatibilityOption.fixedJsonExtract)) {
-                    this.#errors.push(this.#yamlError(declaredOptions, 'Enabling unstable_sqlite_expression_engine requires fixed_json_extract'));
+                    declaredOptions.reportError('Enabling unstable_sqlite_expression_engine requires fixed_json_extract');
                 }
             }
         }
@@ -74,35 +93,30 @@ export class SyncConfigFromYaml {
             compatibility = CompatibilityContext.FULL_BACKWARDS_COMPATIBILITY;
         }
         // Bucket definitions using explicit parameter and data queries.
-        const bucketMap = parsed.get('bucket_definitions');
-        const streamMap = parsed.get('streams');
-        const globalCtes = parsed.get('with');
+        const bucketMap = rootState.get('bucket_definitions')?.requireMap();
+        const streamMap = rootState.get('streams')?.requireMap();
+        const globalCtes = rootState.get('with')?.requireMap();
+        const eventMap = rootState.get('event_definitions')?.requireMap();
         let result;
         if (compatibility.edition >= CompatibilityEdition.COMPILED_STREAMS) {
-            result = this.#compileSyncPlan(bucketMap, streamMap, globalCtes, compatibility);
+            result = this.#compileSyncPlan(bucketMap, streamMap, globalCtes, eventMap, compatibility);
             this.#warnOnUnusedCtes();
         }
         else {
-            if (globalCtes != null) {
-                // We don't support CTEs at all in this compiler implementation.
-                this.#errors.push(this.#yamlError(globalCtes, 'Common table expressions are not supported without the `sync_config_compiler` option.'));
-            }
-            result = this.#legacyParseBucketDefinitionsAndStreams(bucketMap, streamMap, compatibility);
+            // We don't support CTEs at all in this compiler implementation.
+            globalCtes?.reportError('Common table expressions require edition 3.');
+            const eventCompiler = new SyncStreamsCompiler({
+                defaultSchema: this.options.defaultSchema,
+                schema: this.options.schema,
+                // Editions 1 and 2 don't persist compiled plans. Keep their event behavior stable across deploys and restarts;
+                // moving to edition 3 validates and enables event payload filters.
+                compileEventPayloadFilters: false
+            });
+            this.#compileEventDefinitions(eventMap, eventCompiler);
+            const eventPlan = eventCompiler.toSyncPlan();
+            result = this.#legacyParseBucketDefinitionsAndStreams(bucketMap, streamMap, compatibility, eventPlan.events);
         }
         result.storageVersion = storageVersion;
-        const eventDefinitions = this.#parseEventDefinitions(parsed, compatibility);
-        result.eventDescriptors.push(...eventDefinitions);
-        // Validate that there are no additional properties.
-        // Since these errors don't contain line numbers, do this last.
-        if (!this.#hasFatalError) {
-            const valid = validateSyncRulesSchema(parsed.toJSON());
-            if (!valid) {
-                this.#errors.push(...validateSyncRulesSchema.errors.map((e) => {
-                    return new YamlError(e);
-                }));
-            }
-        }
-        this.#throwOnErrorIfRequested();
         return result;
     }
     get #hasFatalError() {
@@ -119,59 +133,58 @@ export class SyncConfigFromYaml {
      * @see https://docs.powersync.com/sync/advanced/compatibility
      */
     #parseCompatibilityOptions(declaredOptions) {
-        const edition = (declaredOptions.get('edition') ?? CompatibilityEdition.LEGACY);
+        const edition = (declaredOptions.get('edition')?.requireScalar()?.requireNumeric() ??
+            CompatibilityEdition.LEGACY);
         const options = new Map();
         let maxTimeValuePrecision = undefined;
-        let useNewCompiler = false;
-        for (const entry of declaredOptions.items) {
-            const { key: { value: key }, value: { value } } = entry;
-            if (key == 'timestamp_max_precision') {
-                maxTimeValuePrecision = TimeValuePrecision.byName[value];
+        for (const [key, option] of Object.entries(CompatibilityOption.byName)) {
+            const isEnabled = declaredOptions.get(key)?.requireScalar()?.requireBoolean();
+            if (isEnabled != null) {
+                options.set(option, isEnabled);
             }
-            if (key == 'sync_config_compiler') {
-                useNewCompiler = Boolean(value);
-                continue;
-            }
-            const option = CompatibilityOption.byName[key];
-            if (option) {
-                options.set(option, Boolean(value));
+        }
+        const rawMaxTimestampPrecision = declaredOptions.get('timestamp_max_precision')?.requireScalar();
+        if (rawMaxTimestampPrecision != null) {
+            const stringValue = rawMaxTimestampPrecision?.requireString();
+            if (stringValue) {
+                maxTimeValuePrecision = TimeValuePrecision.byName[stringValue];
+                if (!maxTimeValuePrecision) {
+                    const allowed = Object.keys(TimeValuePrecision.byName).join(', ');
+                    rawMaxTimestampPrecision.reportError(`Unknown time precision, allowed are ${allowed}`);
+                }
             }
         }
         const compatibility = new CompatibilityContext({ edition, overrides: options, maxTimeValuePrecision });
         if (maxTimeValuePrecision && !compatibility.isEnabled(CompatibilityOption.timestampsIso8601)) {
-            this.#errors.push(new YamlError(new Error(`'timestamp_max_precision' requires 'timestamps_iso8601' to be enabled.`)));
+            declaredOptions.reportError(`'timestamp_max_precision' requires 'timestamps_iso8601' to be enabled.`);
         }
         return compatibility;
     }
-    #compileSyncPlan(bucketMap, streamMap, globalCtes, compatibility) {
-        if (bucketMap != null) {
-            this.#errors.push(this.#yamlError(bucketMap, `'bucket_definitions' are not supported by the new compiler. Consider using https://powersync-community.github.io/bucket-definitions-to-sync-streams/ to translate them to streams.`));
-        }
+    #compileSyncPlan(bucketMap, streamMap, globalCtes, eventMap, compatibility) {
+        bucketMap?.reportError(`'bucket_definitions' are not supported by the new compiler. Consider using https://powersync-community.github.io/bucket-definitions-to-sync-streams/ to translate them to streams.`);
         if (streamMap == null) {
             this.#errors.push(new YamlError(new Error(`'streams' are required.`)));
         }
         const compiler = new SyncStreamsCompiler(this.options);
         const parseCommonTableExpressions = (from) => {
             const map = new Map();
-            if (from != null) {
-                for (const entry of from.items ?? []) {
-                    const { key: cteNameScalar, value: cteQuery } = entry;
-                    const cteName = cteNameScalar.value;
+            const fromMap = from?.requireMap();
+            if (fromMap != null) {
+                for (const { key: cteName, keyScalar, value } of fromMap.stringKeyedItems()) {
+                    const cteQuery = value.requireScalar();
                     if (this.options.schema) {
                         // Emit a warning if the CTE shadows a name from the schema.
                         const pattern = new TablePattern(this.options.defaultSchema, cteName);
                         if (this.options.schema.getTables(pattern)?.length > 0) {
-                            const error = this.#yamlError(cteNameScalar, 'This common table expression shadows the name of a table in the source schema.');
-                            error.type = 'warning';
-                            this.#errors.push(error);
+                            keyScalar.reportError('This common table expression shadows the name of a table in the source schema.', 'warning');
                         }
                     }
-                    if (this.#expectScalar(cteQuery)) {
-                        const [sql, errorListener] = this.#scalarErrorListener(cteQuery);
+                    if (cteQuery) {
+                        const [sql, errorListener] = this.#scalarErrorListener(cteQuery.node);
                         const parsed = compiler.commonTableExpression(sql, errorListener);
                         if (parsed) {
                             const cte = { subquery: parsed, used: false };
-                            this.#definedCtes.push({ cte, name: cteNameScalar });
+                            this.#definedCtes.push({ cte, name: keyScalar });
                             map.set(cteName, cte);
                         }
                     }
@@ -180,19 +193,16 @@ export class SyncConfigFromYaml {
             return map;
         };
         const parsedGlobalCommonTableExpressions = parseCommonTableExpressions(globalCtes);
-        for (const entry of streamMap?.items ?? []) {
-            const { key: keyScalar, value } = entry;
-            if (!(value instanceof YAMLMap)) {
-                // The json schema validator will flag this later.
-                continue;
-            }
-            const key = keyScalar.toString();
+        for (const { key, keyScalar, value: maybeMap } of streamMap?.stringKeyedItems() ?? []) {
             if (!this.#checkUniqueName(key, keyScalar)) {
                 continue;
             }
+            using value = maybeMap.requireMap();
+            if (value == null)
+                continue;
             const streamCompiler = compiler.stream({
                 name: key,
-                isSubscribedByDefault: value.get('auto_subscribe', true)?.value == true,
+                isSubscribedByDefault: value.get('auto_subscribe')?.requireScalar()?.requireBoolean() == true,
                 priority: this.#parsePriority(value) ?? DEFAULT_BUCKET_PRIORITY,
                 warnOnDangerousParameter: !this.#acceptPotentiallyUnsafeQueries(value)
             });
@@ -200,65 +210,58 @@ export class SyncConfigFromYaml {
             // Add stream-local CTEs, which shadow global definitions.
             parseCommonTableExpressions(value.get('with')).forEach((query, name) => streamCompiler.registerCommonTableExpression(name, query));
             const addQuery = (query) => {
-                if (this.#expectScalar(query)) {
-                    const [sql, errorListener] = this.#scalarErrorListener(query);
+                const scalar = query.requireScalar();
+                if (scalar) {
+                    const [sql, errorListener] = this.#scalarErrorListener(scalar.node);
                     streamCompiler.addQuery(sql, errorListener);
                 }
             };
             const queries = value.get('queries');
-            const query = value.get('query', true);
+            const query = value.get('query');
             if ((queries == null) == (query == null)) {
-                this.#errors.push(this.#yamlError(value, 'One of `queries` or `query` must be given.'));
+                value.reportError('One of `queries` or `query` must be given.');
             }
             if (query) {
                 addQuery(query);
             }
             if (queries) {
-                for (const queryEntry of queries.items) {
+                for (const queryEntry of queries?.requireSequence()?.items ?? []) {
                     addQuery(queryEntry);
                 }
             }
             streamCompiler.finish();
         }
-        // We pass an empty array for eventDefinitions here because those will get parsed in #parseEventDefinitions.
-        return new PrecompiledSyncConfig(compiler.output.toSyncPlan(), compatibility, [], {
+        this.#compileEventDefinitions(eventMap, compiler);
+        return new PrecompiledSyncConfig(compiler.toSyncPlan(), compatibility, {
             defaultSchema: this.options.defaultSchema,
             sourceText: this.yaml
         });
     }
     #warnOnUnusedCtes() {
-        for (const cte of this.#definedCtes) {
-            if (!cte.cte.used) {
-                const error = this.#yamlError(cte.name, `This common table expression isn't referenced.`);
-                error.type = 'warning';
-                this.#errors.push(error);
+        for (const { cte, name } of this.#definedCtes) {
+            if (!cte.used) {
+                name.reportError(`This common table expression isn't referenced.`, 'warning');
             }
         }
     }
-    #legacyParseBucketDefinitionsAndStreams(bucketMap, streamMap, compatibility) {
+    #legacyParseBucketDefinitionsAndStreams(bucketMap, streamMap, compatibility, events) {
         const rules = new SqlSyncRules(this.yaml);
         rules.compatibility = compatibility;
+        rules.eventDefinitions.push(...events.map((event) => new PreparedEventDefinition(event, this.options.defaultSchema)));
         if (bucketMap == null && streamMap == null) {
             this.#errors.push(new YamlError(new Error(`'bucket_definitions' or 'streams' is required`)));
             this.#throwOnErrorIfRequested();
         }
-        if (streamMap != null) {
-            // This is with config.edition <= 2, we want to encourage users with streams to migrate to version 3 to use
-            // compiled sync plans.
-            const error = this.#yamlError(streamMap, 'This is using an alpha version of Sync Streams. We recommend upgrading `config.edition` to version 3 to support the latest features.');
-            error.type = 'warning';
-            this.#errors.push(error);
-        }
-        for (let entry of bucketMap?.items ?? []) {
-            const { key: keyScalar, value } = entry;
-            const key = keyScalar.toString();
+        // This is with config.edition <= 2, we want to encourage users with streams to migrate to version 3 to use
+        // compiled sync plans.
+        streamMap?.reportError('This is using an alpha version of Sync Streams. We recommend upgrading `config.edition` to version 3 to support the latest features.', 'warning');
+        for (const { key, keyScalar, value: maybeMap } of bucketMap?.stringKeyedItems() ?? []) {
             if (!this.#checkUniqueName(key, keyScalar)) {
                 continue;
             }
-            if (value == null || !(value instanceof YAMLMap)) {
-                this.#errors.push(this.#tokenError(keyScalar, `'${key}' bucket definition must be an object`));
+            using value = maybeMap.requireMap(`'${key}' bucket definition must be an object`);
+            if (value == null)
                 continue;
-            }
             const accept_potentially_dangerous_queries = this.#acceptPotentiallyUnsafeQueries(value);
             const parseOptionPriority = this.#parsePriority(value);
             const queryOptions = {
@@ -267,26 +270,28 @@ export class SyncConfigFromYaml {
                 priority: parseOptionPriority,
                 compatibility
             };
-            const parameters = value.get('parameters', true);
-            const dataQueries = value.get('data', true);
+            const parameters = value.get('parameters');
+            const dataQueries = value.require('data')?.requireSequence();
             const descriptor = new SqlBucketDescriptor(key);
-            if (parameters instanceof Scalar) {
+            if (parameters == null) {
+                descriptor.addParameterQuery('SELECT', queryOptions);
+            }
+            else if (parameters.node instanceof Scalar) {
                 this.#withScalar(parameters, (q) => {
                     return descriptor.addParameterQuery(q, queryOptions);
                 });
             }
-            else if (parameters instanceof YAMLSeq) {
-                for (let item of parameters.items) {
-                    this.#withScalar(item, (q) => {
-                        return descriptor.addParameterQuery(q, queryOptions);
-                    });
-                }
-            }
             else {
-                descriptor.addParameterQuery('SELECT', queryOptions);
+                const seq = parameters.requireSequence('Parameters must be a string or array of strings');
+                if (seq != null) {
+                    for (let item of seq.items) {
+                        this.#withScalar(item, (q) => {
+                            return descriptor.addParameterQuery(q, queryOptions);
+                        });
+                    }
+                }
             }
-            if (!(dataQueries instanceof YAMLSeq)) {
-                this.#errors.push(this.#tokenError((dataQueries ?? value), `'data' must be an array`));
+            if (dataQueries == null) {
                 continue;
             }
             for (let query of dataQueries.items) {
@@ -298,31 +303,28 @@ export class SyncConfigFromYaml {
             rules.bucketDataSources.push(...descriptor.dataSources);
             rules.bucketParameterLookupSources.push(...descriptor.parameterIndexLookupCreators);
         }
-        for (const entry of streamMap?.items ?? []) {
-            const { key: keyScalar, value } = entry;
-            const key = keyScalar.toString();
+        for (const { key, keyScalar, value } of streamMap?.stringKeyedItems() ?? []) {
             if (!this.#checkUniqueName(key, keyScalar)) {
                 continue;
             }
+            using map = value.requireMap();
+            if (map == null)
+                continue;
             // We don't support with or multiple queries in streams, those are only supported by the new compiler.
-            const $with = value.get('with');
-            if ($with != null) {
-                this.#errors.push(this.#yamlError($with, 'Common table expressions are not supported without the `sync_config_compiler` option.'));
-            }
-            const queries = value.get('queries');
-            if (queries != null) {
-                this.#errors.push(this.#yamlError(queries, 'Multiple queries not supported without the `sync_config_compiler` option.'));
-            }
-            const accept_potentially_dangerous_queries = value.get('accept_potentially_dangerous_queries', true)?.value == true;
+            map
+                .get('with')
+                ?.reportError('Common table expressions are not supported without the `sync_config_compiler` option.');
+            map.get('queries')?.reportError('Multiple queries not supported without the `sync_config_compiler` option.');
+            const accept_potentially_dangerous_queries = map.get('accept_potentially_dangerous_queries')?.requireScalar()?.requireBoolean() == true;
             const queryOptions = {
                 ...this.options,
                 accept_potentially_dangerous_queries,
-                priority: this.#parsePriority(value),
-                auto_subscribe: value.get('auto_subscribe', true)?.value == true,
+                priority: this.#parsePriority(map),
+                auto_subscribe: map.get('auto_subscribe')?.requireScalar()?.requireBoolean() == true,
                 compatibility
             };
-            const data = value.get('query', true);
-            if (data instanceof Scalar) {
+            const data = map.get('query')?.requireScalar('Must be a string');
+            if (data != null) {
                 this.#withScalar(data, (q) => {
                     const [parsed, errors] = syncStreamFromSql(key, q, queryOptions);
                     rules.bucketSources.push(parsed);
@@ -334,112 +336,78 @@ export class SyncConfigFromYaml {
                     };
                 });
             }
-            else {
-                this.#errors.push(this.#tokenError(data, 'Must be a string.'));
-                continue;
-            }
         }
         return rules;
     }
     #validateStorageVersion(config) {
-        const storageScalar = config.get('storage_version', true);
+        const storageScalar = config.get('storage_version')?.requireScalar();
         if (storageScalar != null) {
-            if (typeof storageScalar.value == 'number') {
-                const rawVersion = storageScalar.value;
-                const version = validateStorageVersion(storageScalar.value);
+            const rawVersion = storageScalar.requireNumeric('Storage version must be numeric');
+            if (rawVersion != null) {
+                const version = validateStorageVersion(rawVersion);
                 if (version == null) {
-                    this.#errors.push(this.#yamlError(storageScalar, `Storage version ${storageScalar.value} is not supported`));
+                    storageScalar.reportError(`Storage version ${rawVersion} is not supported`);
                 }
                 else if (!version.stable) {
-                    const error = this.#yamlError(storageScalar, `Storage version ${version.version} is unstable, and may cause unexpected behavior or stop functioning in any release`);
-                    error.type = 'warning';
-                    this.#errors.push(error);
+                    storageScalar.reportError(`Storage version ${version.version} is unstable, and may cause unexpected behavior or stop functioning in any release`, 'warning');
                 }
                 return version?.version;
             }
-            else {
-                this.#errors.push(this.#yamlError(storageScalar, 'Storage version must be numeric'));
-                return undefined;
-            }
         }
         return undefined;
     }
-    #parseEventDefinitions(parsed, compatibility) {
-        const eventMap = parsed.get('event_definitions');
-        const eventDescriptors = [];
-        for (const event of eventMap?.items ?? []) {
-            const { key, value } = event;
-            if (false == value instanceof YAMLMap) {
-                this.#errors.push(new YamlError(new Error(`Event definitions must be objects.`)));
+    #compileEventDefinitions(eventMap, compiler) {
+        for (const { key: name, value: maybeMap } of eventMap?.stringKeyedItems() ?? []) {
+            using value = maybeMap.requireMap(`Event definitions must be objects.`);
+            if (value == null)
                 continue;
-            }
-            const payloads = value.get('payloads');
-            if (false == payloads instanceof YAMLSeq) {
-                this.#errors.push(new YamlError(new Error(`Event definition payloads must be an array.`)));
+            const payloads = value.get('payloads')?.requireSequence(`Event definition payloads must be an array.`);
+            if (payloads == null)
                 continue;
-            }
-            const eventDescriptor = new SqlEventDescriptor(key.toString(), compatibility);
-            for (let item of payloads.items) {
-                if (!isScalar(item)) {
-                    this.#errors.push(new YamlError(new Error(`Payload queries for events must be scalar.`)));
+            const eventCompiler = compiler.event(name);
+            for (const item of payloads.items) {
+                const itemScalar = item.requireScalar(`Payload queries for events must be scalar.`);
+                if (itemScalar == null)
                     continue;
-                }
-                this.#withScalar(item, (q) => {
-                    return eventDescriptor.addSourceQuery(q, this.options);
-                });
+                const [sql, errorListener] = this.#scalarErrorListener(itemScalar.node);
+                eventCompiler.addSourceQuery(sql, errorListener);
             }
-            eventDescriptors.push(eventDescriptor);
         }
-        return eventDescriptors;
     }
     #checkUniqueName(name, literal) {
         if (this.#definitionNames.has(name)) {
-            this.#errors.push(this.#tokenError(literal, 'Duplicate stream or bucket definition.'));
+            literal.reportError('Duplicate stream or bucket definition.');
             return false;
         }
         this.#definitionNames.add(name);
         return true;
     }
     #parsePriority(value) {
-        if (value.has('priority')) {
-            const priorityValue = value.get('priority', true);
-            if (typeof priorityValue.value != 'number' || !isValidPriority(priorityValue.value)) {
-                this.#errors.push(this.#tokenError(priorityValue, 'Invalid priority, expected a number between 0 and 3 (inclusive).'));
-            }
-            else {
-                return priorityValue.value;
-            }
+        const message = 'Invalid priority, expected a number between 0 and 3 (inclusive).';
+        const priorityScalar = value.get('priority')?.requireScalar();
+        const rawPriority = priorityScalar?.requireNumeric(message);
+        if (priorityScalar == null || rawPriority == null)
+            return;
+        if (!isValidPriority(rawPriority)) {
+            priorityScalar.reportError(message);
+            return;
         }
+        return rawPriority;
     }
     #acceptPotentiallyUnsafeQueries(definition) {
-        return definition.get('accept_potentially_dangerous_queries', true)?.value == true;
-    }
-    #yamlError(node, message) {
-        if (node.range != null) {
-            const [start, _, end] = node.range;
-            return new YamlError(new Error(message), { start, end });
-        }
-        else {
-            return new YamlError(new Error(message));
-        }
+        return definition.get('accept_potentially_dangerous_queries')?.requireScalar()?.requireBoolean() ?? false;
     }
     #tokenError(token, message) {
         const start = token?.srcToken?.offset ?? 0;
         const end = start + 1;
         return new YamlError(new Error(message), { start, end });
     }
-    #expectScalar(node) {
-        if (!(node instanceof Scalar)) {
-            this.#errors.push(this.#yamlError(node, 'Expected a scalar value here.'));
-            return false;
-        }
-        return true;
-    }
-    #withScalar(scalar, cb) {
-        if (!this.#expectScalar(scalar)) {
+    #withScalar(state, cb) {
+        const scalar = state.requireScalar();
+        if (scalar == null) {
             return;
         }
-        const value = scalar.toString();
+        const value = scalar.node.toString();
         const wrapped = (value) => {
             try {
                 return cb(value);
@@ -453,7 +421,7 @@ export class SyncConfigFromYaml {
         };
         const result = wrapped(value);
         for (let err of result.errors) {
-            this.#addErrorFromScalar(scalar, value, err);
+            this.#addErrorFromScalar(scalar.node, value, err);
         }
         return;
     }