@usearazzo/parser 1.0.1-alpha.0

package/src/parse-runtime-expression.mjs

@@ -0,0 +1,73 @@
+import { parse as parseRuntimeExpression, ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';
+
+/**
+ * Options for parsing Arazzo Runtime Expressions.
+ * @public
+ */
+
+/**
+ * Result of parsing an Arazzo Runtime Expression: the foundation ParseResult
+ * bound to the AST node type this parser produces.
+ * @public
+ */
+
+/**
+ * Default options for parsing Arazzo Runtime Expressions. Empty on purpose:
+ * the underlying grammar package supplies its own defaults, including a fresh
+ * ASTTranslator per call.
+ * @public
+ */
+export const defaultOptions = {};
+
+/**
+ * Parses an Arazzo Runtime Expression (e.g. `$inputs.username`,
+ * `$steps.myStep.outputs.result`, `$response.body#/pets/0/id`) into its AST.
+ *
+ * A pure, context-free syntax parser: the expression string in, an AST plus
+ * position-carrying diagnostics (`result.matched` / `result.maxMatched`) out.
+ * No evaluation is performed and no document is required; evaluating the
+ * parsed expression against runtime state is the runner's responsibility.
+ *
+ * The expression must be the bare form without surrounding braces. Splitting a
+ * `{expression}` template into literal and expression spans is left to
+ * `@swaggerexpert/arazzo-runtime-expression`'s own `extract`/`interpolate`
+ * functions, which remain a foundation dependency rather than being wrapped
+ * here.
+ *
+ * @param expression - The runtime expression source string
+ * @param options - Parse options (uses defaultOptions when not provided)
+ * @returns The parse result: `{ result, tree, stats, trace }`. On success,
+ * `result.success` is `true` and `tree` holds the AST. On failure,
+ * `result.success` is `false`, `tree` is `undefined`, and `result.maxMatched`
+ * gives the offset into `expression` up to which parsing succeeded.
+ * @throws TypeError - When `expression` is not a string.
+ * @throws ArazzoRuntimeExpressionParseError - When parsing fails for a reason
+ * other than invalid syntax (an unexpected internal error). Invalid syntax is
+ * never thrown; it is reported through the returned `result`.
+ *
+ * @example
+ * Valid expression
+ * ```typescript
+ * import { parseRuntimeExpression } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseRuntimeExpression('$steps.myStep.outputs.result');
+ * // result.success === true
+ * // tree === { type: 'StepsExpression', stepId: 'myStep', field: 'outputs', outputName: 'result' }
+ * ```
+ *
+ * @example
+ * Invalid expression
+ * ```typescript
+ * import { parseRuntimeExpression } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseRuntimeExpression('$unknown.thing');
+ * // result.success === false
+ * // tree === undefined
+ * // result.maxMatched === 0 - the offset parsing failed at
+ * ```
+ * @public
+ */
+export function parse(expression, options = defaultOptions) {
+  return parseRuntimeExpression(expression, options);
+}
+export { ArazzoRuntimeExpressionParseError };

package/src/resolve/resolvers/memory/index.cjs

@@ -0,0 +1,52 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+/**
+ * @public
+ */
+
+/**
+ * Serves an in-memory document under exactly one URI.
+ * @public
+ */
+class MemoryResolver extends _empty.Resolver {
+  document;
+  uri;
+  constructor({
+    document,
+    uri
+  }) {
+    super({
+      name: 'memory'
+    });
+    this.document = document;
+    // must match the File.uri derivation in apidom-reference's parse()
+    this.uri = _empty.url.sanitize(_empty.url.stripHash(uri));
+  }
+  canRead(file) {
+    if (file.uri === this.uri) return true;
+    // a URI under this resolver's synthetic memory:// base can only be a relative URL
+    // resolved against it; apidom records the message of an error thrown here verbatim
+    // in the source description annotation, whereas an error thrown from read() would
+    // be wrapped and its message lost
+    if (this.uri.startsWith('memory://') && file.uri.startsWith(`${this.uri}/`)) {
+      throw new _empty.ResolverError('relative URL cannot be resolved because the parent document was parsed from ' + 'inline content. Provide resolve.baseURI or an absolute $self.');
+    }
+    return false;
+  }
+  async read(file) {
+    try {
+      const encoder = new TextEncoder();
+      return encoder.encode(this.document);
+    } catch (error) {
+      throw new _empty.ResolverError(`Error opening file "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+var _default = exports.default = MemoryResolver;

package/src/resolve/resolvers/memory/index.mjs

@@ -0,0 +1,47 @@
+import { url, Resolver, ResolverError } from '@speclynx/apidom-reference/configuration/empty';
+
+/**
+ * @public
+ */
+
+/**
+ * Serves an in-memory document under exactly one URI.
+ * @public
+ */
+class MemoryResolver extends Resolver {
+  document;
+  uri;
+  constructor({
+    document,
+    uri
+  }) {
+    super({
+      name: 'memory'
+    });
+    this.document = document;
+    // must match the File.uri derivation in apidom-reference's parse()
+    this.uri = url.sanitize(url.stripHash(uri));
+  }
+  canRead(file) {
+    if (file.uri === this.uri) return true;
+    // a URI under this resolver's synthetic memory:// base can only be a relative URL
+    // resolved against it; apidom records the message of an error thrown here verbatim
+    // in the source description annotation, whereas an error thrown from read() would
+    // be wrapped and its message lost
+    if (this.uri.startsWith('memory://') && file.uri.startsWith(`${this.uri}/`)) {
+      throw new ResolverError('relative URL cannot be resolved because the parent document was parsed from ' + 'inline content. Provide resolve.baseURI or an absolute $self.');
+    }
+    return false;
+  }
+  async read(file) {
+    try {
+      const encoder = new TextEncoder();
+      return encoder.encode(this.document);
+    } catch (error) {
+      throw new ResolverError(`Error opening file "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+export default MemoryResolver;

package/types/parser.d.ts

@@ -0,0 +1,260 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+import type { ApiDOMReferenceOptions } from '@speclynx/apidom-reference/configuration/empty';
+import { ArazzoCriterionParseError } from '@swaggerexpert/arazzo-criterion';
+import { ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';
+import { ASTTranslator } from '@swaggerexpert/arazzo-runtime-expression';
+import { ASTTranslator as ASTTranslator_2 } from '@swaggerexpert/arazzo-criterion';
+import { ConditionAST as CriterionConditionAST } from '@swaggerexpert/arazzo-criterion';
+import { ParseOptions } from '@swaggerexpert/arazzo-runtime-expression';
+import { ParseOptions as ParseOptions_2 } from '@swaggerexpert/arazzo-criterion';
+import { ParseResult } from '@swaggerexpert/arazzo-runtime-expression';
+import { ParseResult as ParseResult_2 } from '@swaggerexpert/arazzo-criterion';
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { PartialDeep } from 'type-fest';
+import { ASTNode as RuntimeExpressionASTNode } from '@swaggerexpert/arazzo-runtime-expression';
+
+export { ArazzoCriterionParseError }
+
+export { ArazzoRuntimeExpressionParseError }
+
+export { CriterionConditionAST }
+
+/**
+ * Default reference options for parsing Arazzo Documents.
+ * @public
+ */
+export declare const defaultParseArazzoOptions: ParseArazzoOptions;
+
+/**
+ * Default options for parsing Arazzo "simple" criterion conditions. Empty on
+ * purpose: the underlying grammar package supplies its own defaults, including
+ * a fresh ASTTranslator per call.
+ * @public
+ */
+export declare const defaultParseCriterionConditionOptions: ParseCriterionConditionOptions;
+
+/**
+ * Default reference options for parsing OpenAPI Documents.
+ * @public
+ */
+export declare const defaultParseOpenAPIOptions: ParseOpenAPIOptions;
+
+/**
+ * Default options for parsing Arazzo Runtime Expressions. Empty on purpose:
+ * the underlying grammar package supplies its own defaults, including a fresh
+ * ASTTranslator per call.
+ * @public
+ */
+export declare const defaultParseRuntimeExpressionOptions: ParseRuntimeExpressionOptions;
+
+/**
+ * Parses an Arazzo Document from an object.
+ * @param source - The Arazzo Document as a plain object
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+export declare function parseArazzo(source: Record<string, unknown>, options?: ParseArazzoOptions): Promise<ParseResultElement>;
+
+/**
+ * Parses an Arazzo Document from a string or URI.
+ * @param source - The Arazzo Document as string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+export declare function parseArazzo(source: string, options?: ParseArazzoOptions): Promise<ParseResultElement>;
+
+/**
+ * Parses an Arazzo Document from a string, object, or URI.
+ * @param source - The Arazzo Document as a plain object, string content, or URI
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+export declare function parseArazzo(source: string | Record<string, unknown>, options?: ParseArazzoOptions): Promise<ParseResultElement>;
+
+/**
+ * Options for parsing Arazzo Documents.
+ * @public
+ */
+export declare type ParseArazzoOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * Parses an Arazzo "simple" criterion condition (e.g. `$statusCode == 200`,
+ * `$response.body#/status == 'available' && $response.header.X-Rate-Limit-Remaining > 0`)
+ * into its AST.
+ *
+ * A pure, context-free syntax parser: the condition string in, an AST plus
+ * position-carrying diagnostics (`result.matched` / `result.maxMatched`) out.
+ * No evaluation is performed and no context is required; evaluating the
+ * parsed condition against runtime state is the runner's responsibility.
+ * Embedded runtime expression operands are parsed too: each `RuntimeExpression`
+ * node in the resulting AST carries its own sub-AST, produced by
+ * `@swaggerexpert/arazzo-runtime-expression` (see {@link parseRuntimeExpression}).
+ *
+ * @param condition - The "simple" criterion condition source string
+ * @param options - Parse options (uses defaultOptions when not provided)
+ * @returns The parse result: `{ result, tree, stats, trace }`. On success,
+ * `result.success` is `true` and `tree` holds the AST. On failure,
+ * `result.success` is `false`, `tree` is `undefined`, and `result.maxMatched`
+ * gives the offset into `condition` up to which parsing succeeded.
+ * @throws TypeError - When `condition` is not a string.
+ * @throws ArazzoCriterionParseError - When parsing fails for a reason other
+ * than invalid syntax (an unexpected internal error). Invalid syntax is never
+ * thrown; it is reported through the returned `result`.
+ *
+ * @example
+ * Valid condition
+ * ```typescript
+ * import { parseCriterionCondition } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseCriterionCondition('$statusCode == 200');
+ * // result.success === true
+ * // tree.type === 'BinaryExpression'
+ * ```
+ *
+ * @example
+ * Invalid condition
+ * ```typescript
+ * import { parseCriterionCondition } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseCriterionCondition('$statusCode ===');
+ * // result.success === false
+ * // tree === undefined
+ * // result.maxMatched - the offset parsing failed at
+ * ```
+ * @public
+ */
+export declare function parseCriterionCondition(condition: string, options?: ParseCriterionConditionOptions): ParseCriterionConditionResult;
+
+/**
+ * Options for parsing Arazzo "simple" criterion conditions.
+ * @public
+ */
+export declare type ParseCriterionConditionOptions = ParseOptions_2<ASTTranslator_2>;
+
+/**
+ * Result of parsing an Arazzo "simple" criterion condition: the foundation
+ * ParseResult bound to the AST node type this parser produces.
+ * @public
+ */
+export declare type ParseCriterionConditionResult = ParseResult_2<CriterionConditionAST>;
+
+/**
+ * Error thrown by `parseArazzo` and `parseOpenAPI` when parsing fails for any
+ * reason. The original error is available via the `cause` property.
+ * @public
+ */
+export declare class ParseError extends ApiDOMError {
+    constructor(message?: string, options?: ApiDOMErrorOptions);
+}
+
+/**
+ * Parses an OpenAPI Document from an object.
+ * @param source - The OpenAPI Document as a plain object
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+export declare function parseOpenAPI(source: Record<string, unknown>, options?: ParseOpenAPIOptions): Promise<ParseResultElement>;
+
+/**
+ * Parses an OpenAPI Document from a string or URI.
+ * @param source - The OpenAPI Document as string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+export declare function parseOpenAPI(source: string, options?: ParseOpenAPIOptions): Promise<ParseResultElement>;
+
+/**
+ * Parses an OpenAPI Document from a string, object, or URI.
+ * @param source - The OpenAPI Document as a plain object, string content, or URI
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+export declare function parseOpenAPI(source: string | Record<string, unknown>, options?: ParseOpenAPIOptions): Promise<ParseResultElement>;
+
+/**
+ * Options for parsing OpenAPI Documents.
+ * @public
+ */
+export declare type ParseOpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+export { ParseResultElement }
+
+/**
+ * Parses an Arazzo Runtime Expression (e.g. `$inputs.username`,
+ * `$steps.myStep.outputs.result`, `$response.body#/pets/0/id`) into its AST.
+ *
+ * A pure, context-free syntax parser: the expression string in, an AST plus
+ * position-carrying diagnostics (`result.matched` / `result.maxMatched`) out.
+ * No evaluation is performed and no document is required; evaluating the
+ * parsed expression against runtime state is the runner's responsibility.
+ *
+ * The expression must be the bare form without surrounding braces. Splitting a
+ * `{expression}` template into literal and expression spans is left to
+ * `@swaggerexpert/arazzo-runtime-expression`'s own `extract`/`interpolate`
+ * functions, which remain a foundation dependency rather than being wrapped
+ * here.
+ *
+ * @param expression - The runtime expression source string
+ * @param options - Parse options (uses defaultOptions when not provided)
+ * @returns The parse result: `{ result, tree, stats, trace }`. On success,
+ * `result.success` is `true` and `tree` holds the AST. On failure,
+ * `result.success` is `false`, `tree` is `undefined`, and `result.maxMatched`
+ * gives the offset into `expression` up to which parsing succeeded.
+ * @throws TypeError - When `expression` is not a string.
+ * @throws ArazzoRuntimeExpressionParseError - When parsing fails for a reason
+ * other than invalid syntax (an unexpected internal error). Invalid syntax is
+ * never thrown; it is reported through the returned `result`.
+ *
+ * @example
+ * Valid expression
+ * ```typescript
+ * import { parseRuntimeExpression } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseRuntimeExpression('$steps.myStep.outputs.result');
+ * // result.success === true
+ * // tree === { type: 'StepsExpression', stepId: 'myStep', field: 'outputs', outputName: 'result' }
+ * ```
+ *
+ * @example
+ * Invalid expression
+ * ```typescript
+ * import { parseRuntimeExpression } from '@usearazzo/parser';
+ *
+ * const { result, tree } = parseRuntimeExpression('$unknown.thing');
+ * // result.success === false
+ * // tree === undefined
+ * // result.maxMatched === 0 - the offset parsing failed at
+ * ```
+ * @public
+ */
+export declare function parseRuntimeExpression(expression: string, options?: ParseRuntimeExpressionOptions): ParseRuntimeExpressionResult;
+
+/**
+ * Options for parsing Arazzo Runtime Expressions.
+ * @public
+ */
+export declare type ParseRuntimeExpressionOptions = ParseOptions<ASTTranslator>;
+
+/**
+ * Result of parsing an Arazzo Runtime Expression: the foundation ParseResult
+ * bound to the AST node type this parser produces.
+ * @public
+ */
+export declare type ParseRuntimeExpressionResult = ParseResult<RuntimeExpressionASTNode>;
+
+export { RuntimeExpressionASTNode }
+
+export { }