@ja-platform/parser-expressions 0.0.0-dev-20261019214152 → 0.0.0-stage

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +2 -111
  2. package/package.json +3 -37
  3. package/dist/@types/CombinedParser.d.ts +0 -11
  4. package/dist/@types/ExpressionParser.d.ts +0 -12
  5. package/dist/@types/code-parsers/CodeParser.d.ts +0 -25
  6. package/dist/@types/code-parsers/JavaScriptParser.d.ts +0 -18
  7. package/dist/@types/definitions/ValidationContext.d.ts +0 -8
  8. package/dist/@types/expressions/AbstractExpression.d.ts +0 -42
  9. package/dist/@types/expressions/EvaluatedExpression.d.ts +0 -34
  10. package/dist/@types/expressions/constant/ConstantExpression.d.ts +0 -28
  11. package/dist/@types/expressions/function/FunctionExpression.d.ts +0 -37
  12. package/dist/@types/expressions/index.d.ts +0 -8
  13. package/dist/@types/expressions/shorthand/FormatShorthandExpression.d.ts +0 -31
  14. package/dist/@types/expressions/shorthand/ShorthandExpression.d.ts +0 -42
  15. package/dist/@types/expressions/text/AbstractFormatExpression.d.ts +0 -43
  16. package/dist/@types/expressions/text/FormatStringExpression.d.ts +0 -18
  17. package/dist/@types/index.d.ts +0 -9
  18. package/dist/@types/tokens/AbstractToken.d.ts +0 -12
  19. package/dist/@types/tokens/code/CodeToken.d.ts +0 -142
  20. package/dist/@types/tokens/code/IdentifierToken.d.ts +0 -12
  21. package/dist/@types/tokens/code/JSToken.d.ts +0 -31
  22. package/dist/@types/tokens/code/PrefixToken.d.ts +0 -9
  23. package/dist/@types/tokens/index.d.ts +0 -8
  24. package/dist/@types/tokens/text/PlaceholderToken.d.ts +0 -12
  25. package/dist/@types/tokens/text/TextToken.d.ts +0 -12
  26. package/dist/@types/utils/parserUtils.d.ts +0 -7
  27. package/dist/@types/utils/tokenUtils.d.ts +0 -11
  28. package/dist/@types/utils/valueFormatting.d.ts +0 -9
  29. package/dist/CombinedParser.js +0 -24
  30. package/dist/CombinedParser.js.map +0 -1
  31. package/dist/ExpressionParser.js +0 -20
  32. package/dist/ExpressionParser.js.map +0 -1
  33. package/dist/code-parsers/CodeParser.js +0 -45
  34. package/dist/code-parsers/CodeParser.js.map +0 -1
  35. package/dist/code-parsers/JavaScriptParser.js +0 -56
  36. package/dist/code-parsers/JavaScriptParser.js.map +0 -1
  37. package/dist/definitions/ValidationContext.js +0 -3
  38. package/dist/definitions/ValidationContext.js.map +0 -1
  39. package/dist/expressions/AbstractExpression.js +0 -47
  40. package/dist/expressions/AbstractExpression.js.map +0 -1
  41. package/dist/expressions/EvaluatedExpression.js +0 -102
  42. package/dist/expressions/EvaluatedExpression.js.map +0 -1
  43. package/dist/expressions/constant/ConstantExpression.js +0 -53
  44. package/dist/expressions/constant/ConstantExpression.js.map +0 -1
  45. package/dist/expressions/function/FunctionExpression.js +0 -79
  46. package/dist/expressions/function/FunctionExpression.js.map +0 -1
  47. package/dist/expressions/index.js +0 -25
  48. package/dist/expressions/index.js.map +0 -1
  49. package/dist/expressions/shorthand/FormatShorthandExpression.js +0 -60
  50. package/dist/expressions/shorthand/FormatShorthandExpression.js.map +0 -1
  51. package/dist/expressions/shorthand/ShorthandExpression.js +0 -90
  52. package/dist/expressions/shorthand/ShorthandExpression.js.map +0 -1
  53. package/dist/expressions/text/AbstractFormatExpression.js +0 -178
  54. package/dist/expressions/text/AbstractFormatExpression.js.map +0 -1
  55. package/dist/expressions/text/FormatStringExpression.js +0 -44
  56. package/dist/expressions/text/FormatStringExpression.js.map +0 -1
  57. package/dist/index.js +0 -29
  58. package/dist/index.js.map +0 -1
  59. package/dist/tokens/AbstractToken.js +0 -22
  60. package/dist/tokens/AbstractToken.js.map +0 -1
  61. package/dist/tokens/code/CodeToken.js +0 -33
  62. package/dist/tokens/code/CodeToken.js.map +0 -1
  63. package/dist/tokens/code/IdentifierToken.js +0 -28
  64. package/dist/tokens/code/IdentifierToken.js.map +0 -1
  65. package/dist/tokens/code/JSToken.js +0 -251
  66. package/dist/tokens/code/JSToken.js.map +0 -1
  67. package/dist/tokens/code/PrefixToken.js +0 -24
  68. package/dist/tokens/code/PrefixToken.js.map +0 -1
  69. package/dist/tokens/index.js +0 -31
  70. package/dist/tokens/index.js.map +0 -1
  71. package/dist/tokens/text/PlaceholderToken.js +0 -25
  72. package/dist/tokens/text/PlaceholderToken.js.map +0 -1
  73. package/dist/tokens/text/TextToken.js +0 -28
  74. package/dist/tokens/text/TextToken.js.map +0 -1
  75. package/dist/tsconfig.tsbuildinfo +0 -1
  76. package/dist/utils/parserUtils.js +0 -19
  77. package/dist/utils/parserUtils.js.map +0 -1
  78. package/dist/utils/tokenUtils.js +0 -43
  79. package/dist/utils/tokenUtils.js.map +0 -1
  80. package/dist/utils/valueFormatting.js +0 -34
  81. package/dist/utils/valueFormatting.js.map +0 -1
package/README.md CHANGED
@@ -1,112 +1,3 @@
1
- # JourneyApps Platform Expressions
1
+ # Temporary Holding Version
2
2
 
3
- `@ja-platform/parser-expressions` parses and represents JourneyApps Platform expressions, preserves source tokens, and supports validation, reference analysis, and source editing. JavaScript code is parsed with Babel; execution belongs to the host.
4
-
5
- ## Expression types
6
-
7
- | Expression | Example source | Use |
8
- | --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
9
- | `ConstantExpression` | `hello`, `42`, `false`, `"hello"` | Text by default; an explicit value type can parse numbers or booleans. `raw()` always preserves source. |
10
- | `ShorthandExpression` | `user.name`, `items[0].name` | A reference resolved through the scope. Bare function calls and arithmetic are not shorthand references. |
11
- | `FormatShorthandExpression` | `price:.2f` | A shorthand reference with a format specifier, commonly used inside `{price:.2f}`. |
12
- | `EvaluatedExpression` | `$:count + 1`, `$:true`, `$:{thing: 'other'}` | Explicitly evaluated code. Its code token contains the language's syntax tree. |
13
- | `FunctionExpression` | `$:getGreeting(true)` | An evaluated expression whose body is a function call. Provides call-specific inspection and argument edits. |
14
- | `FormatStringExpression` | `Hello {user.name}, {$:getGreeting(true)}` | Text mixed with placeholder expressions. `tokens` contains the complete source sequence; `parameters` exposes the placeholder expressions. Plain text is also a valid format string. |
15
-
16
- `AbstractExpression` is the shared base for source tokens and positions. Constants expose `.value()`, shorthand references expose `.path`, and evaluated expressions (including functions) expose `.code()` and `.codeToken`. `TextToken.decodedText` decodes doubled braces. The former `.text()`, expression/token `.stringify()`, and shared `.expression` field have been removed. Every expression owns source tokens and supports `raw()`, `clone()`, and `isValid()`.
17
-
18
- `FunctionExpression` extends `EvaluatedExpression`, and `FormatShorthandExpression` extends `ShorthandExpression`.
19
-
20
- Constants use an explicitly supplied value type. The consumer selects an explicit `ValueType<T>` to parse a typed value, without inferring a type from source. `TextType`, `NumberType`, and `BooleanType` can also parse dynamically resolved values. Number parsing rejects empty input, non-numeric values, and non-finite numbers. Boolean parsing accepts booleans, true/false text, and finite numeric values (zero is false). Attribute defaults, truthiness conditions, and range restrictions remain consumer policies.
21
-
22
- Executable code requires `$:`. Arrays, objects, and conditional expressions live inside the code token's Babel AST; they do not have separate JourneyApps Platform expression classes. A shorthand such as `user.name` can omit the prefix because it identifies a value to retrieve.
23
-
24
- ## Parsing
25
-
26
- Choose a parser according to the syntax the field accepts. Each expression's static `parse()` method is a convenience around its corresponding parser.
27
-
28
- ```ts
29
- import {
30
- CombinedParser,
31
- EvaluatedExpression,
32
- EvaluatedExpressionParser,
33
- FunctionExpressionParser,
34
- ConstantExpression,
35
- ConstantExpressionParser
36
- } from '@ja-platform/parser-expressions';
37
-
38
- const attributeParser = new CombinedParser<EvaluatedExpression | ConstantExpression>([
39
- new FunctionExpressionParser(),
40
- new EvaluatedExpressionParser(),
41
- new ConstantExpressionParser()
42
- ]);
43
-
44
- attributeParser.tryParse('$:count()'); // FunctionExpression
45
- attributeParser.tryParse('$:count + 1'); // EvaluatedExpression
46
- attributeParser.tryParse('42'); // ConstantExpression with value "42"
47
- attributeParser.tryParse('false'); // ConstantExpression with value "false"
48
- attributeParser.tryParse('hello'); // ConstantExpression with value "hello"
49
- ```
50
-
51
- `CombinedParser` tries parsers in order and returns the first match. Put specific parsers before broader ones: function calls are also evaluated expressions, and the constant parser matches any remaining input. The default `parseExpression()` recognizes evaluated code and shorthand references first, then preserves unmatched input as constant text.
52
-
53
- `ConstantExpressionParser` defaults to text, or accepts an explicit type: `new ConstantExpressionParser(NumberType)`. It replaces the text, raw-text, primitive and numeric constant parsers. One generic `ConstantExpression<T>` stores the typed value and original source tokens; no literal token or primitive subclasses are needed.
54
-
55
- `ExpressionParser` is an abstract base with `.tryParse()` for optional matches and `.parse()` for required valid matches. Concrete parsers and `CombinedParser` inherit `.parse()`; expression static parse methods delegate to it.
56
-
57
- Syntax-specific parsers return `null` for unrecognized syntax but can throw for malformed syntax belonging to that parser. A constant parser accepts the remaining syntax and throws if its selected type cannot parse the value. Static `parse()` requires a valid expression. Directly constructed or edited expressions can be checked with `isValid()`.
58
-
59
- Constructors require prepared `tokens` and any type-specific options; they do not parse source or create fallback tokens. Use `ConstantExpression.parse(source, TextType)` for constant text. It also replaces the former `deserialize()` factories, which encoded typed literals:
60
-
61
- ```ts
62
- ConstantExpression.parse('42', TextType).value(); // "42"
63
- ConstantExpression.parse('045', NumberType).value(); // 45
64
- ConstantExpression.parse('045', NumberType).raw(); // "045"
65
- ConstantExpression.parse('false', BooleanType).value(); // false
66
- NumberType.parse('45'); // 45, also usable for resolved values
67
- ConstantExpression.parse('45px', NumberType); // throws SyntaxError
68
- ConstantExpression.parse('false', TextType).value(); // "false"
69
- ConstantExpression.parse('null', TextType).value(); // "null"
70
- ConstantExpression.parse('"hello"', TextType).value(); // '"hello"'
71
- ```
72
-
73
- Constant parsing does not quote or escape text. When editing function arguments, supply valid source in the code token's language through `withArgumentSources()` or `withArguments()`. For example, `withArgumentSources(['"hello"', 'false'])` inserts a JavaScript string and boolean into a JavaScript call. The JavaScript code token owns their syntax tree.
74
-
75
- ## Format strings and source tokens
76
-
77
- ```ts
78
- import { FormatStringExpression } from '@ja-platform/parser-expressions';
79
-
80
- const expression = FormatStringExpression.parse('Hello {user.name}, {$:getGreeting(true)}');
81
-
82
- expression.tokens; // TextToken, PlaceholderToken, TextToken, PlaceholderToken
83
- expression.parameters; // ShorthandExpression, FunctionExpression
84
- expression.raw(); // The original source, including braces and whitespace
85
- ```
86
-
87
- The token structure is:
88
-
89
- ```text
90
- FormatStringExpression
91
- ├── TextToken("Hello ")
92
- ├── PlaceholderToken
93
- │ └── ShorthandExpression
94
- │ └── JSToken("user.name", Babel AST)
95
- ├── TextToken(", ")
96
- └── PlaceholderToken
97
- └── FunctionExpression
98
- ├── PrefixToken("$:")
99
- └── JSToken("getGreeting(true)", Babel AST)
100
- ```
101
-
102
- Constant placeholders preserve their text when rendered: `{null}` renders `null`, and `{"hello"}` renders `"hello"`.
103
-
104
- `raw()` joins each token's source representation. It preserves delimiters and escapes; it does not evaluate placeholders. The host resolves references and code, then passes the resolved values to `render(values)`. Double braces, such as `{{user.name}}`, represent literal braces in the rendered text.
105
-
106
- ## Code parsing and editing
107
-
108
- `CodeToken` defines the language-neutral contract for call and reference classification, call inspection, editing, and reference rewriting. `JSToken` supplies the JavaScript implementation and Babel AST. Argument representations belong to the language implementation; use `expression.codeToken.sourceOf(argument)` to read their source. JavaScript arguments remain Babel nodes, accessible through `JSToken` when AST inspection is needed. Use `withArguments()` for JourneyApps Platform expression source or `withArgumentSources()` for source in the token's language.
109
-
110
- `CodeToken.rewriteReferences()` exposes unbound references and direct calls through `CodeReference`, with source tokens for call arguments. Its JavaScript implementation preserves local bindings and source formatting.
111
-
112
- `CodeParser` caches parsing by language and source through a singleton on `globalThis`. Each occurrence receives an independent tree and offsets. Call `CodeParser.getInstance().clear()` after a parsing batch to release cached results without affecting existing expressions.
3
+ This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
package/package.json CHANGED
@@ -1,40 +1,6 @@
1
1
  {
2
2
  "name": "@ja-platform/parser-expressions",
3
- "engines": {
4
- "node": "^22.19.0 || ^24.11.0 || >=26.0.0"
5
- },
6
- "version": "0.0.0-dev-20261019214152",
7
- "description": "JourneyApps Platform expression parsing, representation and reference analysis",
8
- "main": "./dist/index.js",
9
- "typings": "./dist/@types/index.d.ts",
10
- "files": [
11
- "dist"
12
- ],
13
- "dependencies": {
14
- "@babel/parser": "^8.0.7",
15
- "@babel/traverse": "^8.0.7",
16
- "@babel/types": "^8.0.6",
17
- "@ja-platform/parser-type-system": "^0.0.0-dev-20261019214152"
18
- },
19
- "devDependencies": {
20
- "@types/babel__traverse": "^7.28.0",
21
- "vitest": "^5.0.5",
22
- "@vitest/browser": "^5.0.5",
23
- "@vitest/browser-webdriverio": "^5.0.0",
24
- "webdriverio": "^10.1.0"
25
- },
26
- "publishConfig": {
27
- "registry": "https://registry.npmjs.org/",
28
- "access": "public"
29
- },
30
- "repository": {
31
- "type": "git",
32
- "url": "https://github.com/journeyapps-platform/parser.git",
33
- "directory": "packages/expressions"
34
- },
35
- "scripts": {
36
- "test": "pnpm test:node && pnpm test:browser",
37
- "test:browser": "vitest --run --configLoader runner --config vitest.config.browser.ts",
38
- "test:node": "vitest --run --configLoader runner --config vitest.config.unit.ts"
39
- }
3
+ "version": "0.0.0-stage",
4
+ "stub": true,
5
+ "description": "Temporary package placeholder for staged publishing"
40
6
  }
@@ -1,11 +0,0 @@
1
- import { ExpressionParser } from './ExpressionParser';
2
- import { AbstractExpression } from './expressions/AbstractExpression';
3
- import { ExpressionSource } from './tokens';
4
- /**
5
- * Try parsers in order and stop at the first matching expression.
6
- */
7
- export declare class CombinedParser<T extends AbstractExpression = AbstractExpression> extends ExpressionParser<T> {
8
- readonly parsers: readonly ExpressionParser<T>[];
9
- constructor(parsers: readonly ExpressionParser<T>[]);
10
- tryParse(source: ExpressionSource, start?: number): T | null;
11
- }
@@ -1,12 +0,0 @@
1
- import { ExpressionSource } from './tokens';
2
- import { AbstractExpression } from './expressions/AbstractExpression';
3
- /**
4
- * Return null for unrecognized syntax; throw for malformed input belonging to this parser.
5
- */
6
- export declare abstract class ExpressionParser<T extends AbstractExpression = AbstractExpression> {
7
- abstract tryParse(source: ExpressionSource, start?: number): T | null;
8
- /**
9
- * Require a valid match, preserving any syntax error from the concrete parser.
10
- */
11
- parse(source: ExpressionSource, start?: number): T;
12
- }
@@ -1,25 +0,0 @@
1
- /**
2
- * Language-specific parsing injected into the shared code parser.
3
- * Results must support structuredClone; language identifies the grammar used for cache entries.
4
- */
5
- export interface CodeLanguageParser<T> {
6
- readonly language: string;
7
- parse(source: string): T;
8
- }
9
- /**
10
- * Shared code parsing and caching, independent of the language's syntax tree.
11
- */
12
- export declare class CodeParser {
13
- static getInstance(): CodeParser;
14
- private readonly cache;
15
- private readonly limit;
16
- private constructor();
17
- /**
18
- * Releases cached results without affecting existing tokens.
19
- */
20
- clear(): void;
21
- /**
22
- * Reuses language parsing by exact source, returning an independent tree for each occurrence.
23
- */
24
- parse<T>(source: string, parser: CodeLanguageParser<T>): T;
25
- }
@@ -1,18 +0,0 @@
1
- import { Expression } from '@babel/types';
2
- import { CodeLanguageParser } from './CodeParser';
3
- export interface ParsedJavaScript {
4
- ast: Expression;
5
- code: string;
6
- freeIdentifiers: readonly string[];
7
- lexemes: readonly {
8
- start: number;
9
- end: number;
10
- }[];
11
- }
12
- /**
13
- * Parses JavaScript source and preserves the ranges needed for source edits.
14
- */
15
- export declare class JavaScriptParser implements CodeLanguageParser<ParsedJavaScript> {
16
- readonly language = "javascript";
17
- parse(source: string): ParsedJavaScript;
18
- }
@@ -1,8 +0,0 @@
1
- import type { ReferencePath } from '../tokens';
2
- import type { Type } from '@ja-platform/parser-type-system';
3
- /**
4
- * Resolve declared references for expression validation without reading or evaluating values.
5
- */
6
- export interface ValidationContext {
7
- getReference(path: ReferencePath): Type | null;
8
- }
@@ -1,42 +0,0 @@
1
- import { AbstractToken } from '../tokens';
2
- import type { ValidationContext } from '../definitions/ValidationContext';
3
- export interface ExpressionDiagnostic {
4
- token: AbstractToken;
5
- message: string;
6
- }
7
- export interface AbstractExpressionOptions {
8
- start?: number;
9
- /**
10
- * Complete source tokens prepared by a parser or value factory.
11
- * Constructors store these tokens without interpreting their source.
12
- */
13
- tokens: readonly AbstractToken[];
14
- }
15
- /**
16
- * Shared source tokens and positions for concrete expression types.
17
- * Concrete types represent constant text such as `42`, references such as `user.name`,
18
- * evaluated code such as `$:count + 1`, or format strings such as `Hello {user.name}`.
19
- * raw() reproduces source syntax.
20
- */
21
- export declare abstract class AbstractExpression<O extends AbstractExpressionOptions = AbstractExpressionOptions> {
22
- type: string;
23
- options: O;
24
- protected constructor(type: string, options: O);
25
- /**
26
- * Check whether the stored value and tokens represent this expression type.
27
- */
28
- abstract isValid(): boolean;
29
- /**
30
- * Validate references against declarations without evaluating values.
31
- */
32
- validate(_context: ValidationContext): ExpressionDiagnostic[];
33
- clone(): this;
34
- get tokens(): readonly AbstractToken[];
35
- /**
36
- * Reproduce source syntax, including whitespace, delimiters and escapes.
37
- */
38
- raw(): string;
39
- get start(): number | null;
40
- set start(start: number);
41
- toString(): string;
42
- }
@@ -1,34 +0,0 @@
1
- import { ExpressionParser } from '../ExpressionParser';
2
- import { AbstractExpression, AbstractExpressionOptions } from './AbstractExpression';
3
- import { AbstractToken, CodeToken, ExpressionSource } from '../tokens';
4
- /**
5
- * Code explicitly marked for evaluation by the `$:` prefix.
6
- * Examples include `$:count + 1`, `$:true`, `$:{name: user.name}` and `$:[1, 2]`.
7
- * The code token owns the language's syntax tree; the supplied scope executes its code.
8
- * Prefixed calls are specialized by FunctionExpression when using the combined parser.
9
- *
10
- * @example
11
- * ```ts
12
- * EvaluatedExpression.parse('$:count + 1').code(); // 'count + 1'
13
- * EvaluatedExpression.parse('$:{active: true}').raw(); // '$:{active: true}'
14
- * ```
15
- */
16
- export declare class EvaluatedExpression extends AbstractExpression<AbstractExpressionOptions> {
17
- static TYPE: string;
18
- static parse(source: ExpressionSource, start?: number): EvaluatedExpression;
19
- constructor(options: AbstractExpressionOptions);
20
- isValid(): boolean;
21
- get codeToken(): CodeToken;
22
- withCode(token: CodeToken): this;
23
- /**
24
- * Executable code without the evaluation prefix or surrounding source trivia.
25
- */
26
- code(): string;
27
- }
28
- /**
29
- * Recognize the syntax owned by EvaluatedExpression.
30
- */
31
- export declare class EvaluatedExpressionParser extends ExpressionParser<EvaluatedExpression> {
32
- tryParse(source: ExpressionSource, start?: number): EvaluatedExpression | null;
33
- sourceTokens(source: string, start?: number): readonly AbstractToken[];
34
- }
@@ -1,28 +0,0 @@
1
- import { ExpressionParser } from '../../ExpressionParser';
2
- import { AbstractExpression, AbstractExpressionOptions } from '../AbstractExpression';
3
- import { ExpressionSource } from '../../tokens';
4
- import { Type } from '@ja-platform/parser-type-system';
5
- export interface ConstantExpressionOptions<T> extends AbstractExpressionOptions {
6
- value: T;
7
- valueType: Type<T>;
8
- }
9
- /**
10
- * A constant with an explicitly selected value type and preserved source syntax.
11
- * The caller selects the value type; types are never inferred from the source.
12
- */
13
- export declare class ConstantExpression<T = string> extends AbstractExpression<ConstantExpressionOptions<T>> {
14
- static TYPE: string;
15
- static parse<T>(source: ExpressionSource, valueType: Type<T>, start?: number): ConstantExpression<T>;
16
- constructor(options: ConstantExpressionOptions<T>);
17
- get valueType(): Type<T>;
18
- isValid(): boolean;
19
- value(): T;
20
- }
21
- /**
22
- * Parse constants using the supplied type. Place last when composing other syntax.
23
- */
24
- export declare class ConstantExpressionParser<T = string> extends ExpressionParser<ConstantExpression<T>> {
25
- readonly valueType: Type<T>;
26
- constructor(...[valueType]: string extends T ? [valueType?: Type<T>] : [valueType: Type<T>]);
27
- tryParse(source: ExpressionSource, start?: number): ConstantExpression<T>;
28
- }
@@ -1,37 +0,0 @@
1
- import { ExpressionParser } from '../../ExpressionParser';
2
- import { AbstractExpression, AbstractExpressionOptions } from '../AbstractExpression';
3
- import { EvaluatedExpression } from '../EvaluatedExpression';
4
- import { CodeToken, ExpressionSource } from '../../tokens';
5
- /**
6
- * An explicitly evaluated function call, such as `$:save(true)` or `$:worker.save(user.name)`.
7
- * The root code expression must be a call; this type exposes its target and arguments for editing.
8
- *
9
- * @example
10
- * ```ts
11
- * const expression = FunctionExpression.parse('$:save(true)');
12
- * expression.functionName(); // 'save'
13
- * expression.withName('persist').raw(); // '$:persist(true)'
14
- * expression.withArgumentSources(['false']).raw(); // '$:save(false)'
15
- * ```
16
- */
17
- export declare class FunctionExpression extends EvaluatedExpression {
18
- static TYPE: string;
19
- static parse(source: ExpressionSource, start?: number): FunctionExpression;
20
- constructor(options: AbstractExpressionOptions);
21
- isValid(): boolean;
22
- get arguments(): CodeToken['arguments'];
23
- functionName(): string;
24
- withName(name: string): this;
25
- /**
26
- * Replace arguments using expression source in the code token's language.
27
- * Constant text is inserted verbatim; callers supply any required quoting or escaping.
28
- */
29
- withArguments(args: readonly AbstractExpression[]): this;
30
- withArgumentSources(args: readonly string[]): this;
31
- }
32
- /**
33
- * Recognize the syntax owned by FunctionExpression.
34
- */
35
- export declare class FunctionExpressionParser extends ExpressionParser<FunctionExpression> {
36
- tryParse(source: ExpressionSource, start?: number): FunctionExpression | null;
37
- }
@@ -1,8 +0,0 @@
1
- export * from './AbstractExpression';
2
- export * from './EvaluatedExpression';
3
- export * from './shorthand/ShorthandExpression';
4
- export * from './shorthand/FormatShorthandExpression';
5
- export * from './constant/ConstantExpression';
6
- export * from './function/FunctionExpression';
7
- export * from './text/FormatStringExpression';
8
- export * from './text/AbstractFormatExpression';
@@ -1,31 +0,0 @@
1
- import { ExpressionParser } from '../../ExpressionParser';
2
- import { ShorthandExpression, ShorthandExpressionOptions } from './ShorthandExpression';
3
- import { ExpressionSource } from '../../tokens';
4
- export interface FormatShorthandExpressionOptions extends ShorthandExpressionOptions {
5
- format: string;
6
- }
7
- /**
8
- * A shorthand reference with a format specifier, such as `price:.2f`.
9
- * Commonly used inside a format-string placeholder, for example `{price:.2f}`.
10
- * The scope resolves the reference before the format specifier is applied to its value.
11
- *
12
- * @example
13
- * ```ts
14
- * const expression = FormatShorthandExpression.parse('price:.2f');
15
- * expression.path; // ['price']
16
- * expression.format; // '.2f'
17
- * expression.raw(); // 'price:.2f'
18
- * ```
19
- */
20
- export declare class FormatShorthandExpression extends ShorthandExpression<FormatShorthandExpressionOptions> {
21
- static readonly TYPE = "format-shorthand-expression";
22
- static parse(source: ExpressionSource, start?: number): FormatShorthandExpression;
23
- constructor(options: FormatShorthandExpressionOptions);
24
- isValid(): boolean;
25
- }
26
- /**
27
- * Recognize the syntax owned by FormatShorthandExpression.
28
- */
29
- export declare class FormatShorthandExpressionParser extends ExpressionParser<FormatShorthandExpression> {
30
- tryParse(source: ExpressionSource, start?: number): FormatShorthandExpression | null;
31
- }
@@ -1,42 +0,0 @@
1
- import { ExpressionParser } from '../../ExpressionParser';
2
- import { AbstractExpression, AbstractExpressionOptions, ExpressionDiagnostic } from '../AbstractExpression';
3
- import { CodeToken, ExpressionSource, ReferencePath } from '../../tokens';
4
- import type { ValidationContext } from '../../definitions/ValidationContext';
5
- import type { Type } from '@ja-platform/parser-type-system';
6
- export interface ShorthandExpressionOptions extends AbstractExpressionOptions {
7
- format?: string;
8
- }
9
- /**
10
- * A reference resolved through the scope without an evaluation prefix.
11
- * Examples include `user.name`, `items[0].name` and `user['name']`.
12
- * Dynamic keys, call receivers, optional chains and arithmetic are not shorthand references.
13
- *
14
- * @example
15
- * ```ts
16
- * ShorthandExpression.parse('user.name').path; // ['user', 'name']
17
- * ShorthandExpression.parse('items[0].name').raw(); // 'items[0].name'
18
- * ```
19
- */
20
- export declare class ShorthandExpression<O extends ShorthandExpressionOptions = ShorthandExpressionOptions> extends AbstractExpression<O> {
21
- static TYPE: string;
22
- static parse(source: ExpressionSource, start?: number): ShorthandExpression;
23
- constructor(options: O);
24
- get format(): string | null;
25
- get codeToken(): CodeToken;
26
- isValid(): boolean;
27
- get path(): ReferencePath;
28
- /**
29
- * Resolve the referenced type without evaluating its value or retaining the result.
30
- */
31
- resolveType(context: ValidationContext): Type | null;
32
- /**
33
- * Report an unresolved reference using its original source token.
34
- */
35
- validate(context: ValidationContext): ExpressionDiagnostic[];
36
- }
37
- /**
38
- * Recognize the syntax owned by ShorthandExpression.
39
- */
40
- export declare class ShorthandExpressionParser extends ExpressionParser<ShorthandExpression> {
41
- tryParse(source: ExpressionSource, start?: number): ShorthandExpression | null;
42
- }
@@ -1,43 +0,0 @@
1
- import { ExpressionParser } from '../../ExpressionParser';
2
- import { AbstractToken, ExpressionSource, TextToken, PlaceholderToken } from '../../tokens';
3
- import type { ValidationContext } from '../../definitions/ValidationContext';
4
- import { AbstractExpression, AbstractExpressionOptions, ExpressionDiagnostic } from '../AbstractExpression';
5
- export interface AbstractFormatExpressionOptions<P extends AbstractExpression> extends AbstractExpressionOptions {
6
- tokens: readonly (TextToken | PlaceholderToken<P>)[];
7
- }
8
- /**
9
- * Shared format text, placeholder tokens, source positions, and rendering.
10
- */
11
- export declare abstract class AbstractFormatExpression<T extends AbstractFormatExpression<T, P>, P extends AbstractExpression = AbstractExpression> extends AbstractExpression<AbstractFormatExpressionOptions<P>> {
12
- get tokens(): readonly (TextToken | PlaceholderToken<P>)[];
13
- isValid(): boolean;
14
- get parameters(): readonly P[];
15
- protected abstract getParser(): AbstractFormatExpressionParser<T, P>;
16
- withParameters(parameters: readonly P[]): T;
17
- /**
18
- * Validate each placeholder against the supplied declarations.
19
- */
20
- validate(context: ValidationContext): ExpressionDiagnostic[];
21
- /**
22
- * Assemble the text using resolved placeholder values in parameter order.
23
- * This does not parse source or evaluate parameters.
24
- *
25
- * @example
26
- * ```ts
27
- * FormatStringExpression.parse('Hello {user.name}').render(['Sam']); // 'Hello Sam'
28
- * ```
29
- */
30
- render(values: readonly unknown[]): string;
31
- toString(): string;
32
- }
33
- export declare abstract class AbstractFormatExpressionParser<T extends AbstractFormatExpression<T, P>, P extends AbstractExpression = AbstractExpression> extends ExpressionParser<T> {
34
- protected abstract parsePlaceholder(source: ExpressionSource, start: number): P;
35
- protected abstract createExpression(options: AbstractFormatExpressionOptions<P>): T;
36
- /**
37
- * Reparse replacements through the concrete grammar, retaining their expression kind.
38
- */
39
- placeholder(expression: AbstractExpression, start: number): PlaceholderToken<P>;
40
- protected validateToken(token: AbstractToken): asserts token is TextToken | PlaceholderToken<P>;
41
- tryParse(source: ExpressionSource, start?: number): T;
42
- tokens(source: string, offset?: number): (TextToken | PlaceholderToken<P>)[];
43
- }
@@ -1,18 +0,0 @@
1
- import { ExpressionSource } from '../../tokens';
2
- import { EvaluatedExpression } from '../EvaluatedExpression';
3
- import { ShorthandExpression } from '../shorthand/ShorthandExpression';
4
- import { AbstractFormatExpression, AbstractFormatExpressionOptions, AbstractFormatExpressionParser } from './AbstractFormatExpression';
5
- /**
6
- * Format text supporting references, formatted references, and explicitly evaluated code.
7
- */
8
- export declare class FormatStringExpression extends AbstractFormatExpression<FormatStringExpression, ShorthandExpression | EvaluatedExpression> {
9
- static readonly TYPE = "format-string";
10
- static parse(source: ExpressionSource, start?: number): FormatStringExpression;
11
- constructor(options: AbstractFormatExpressionOptions<ShorthandExpression | EvaluatedExpression>);
12
- protected getParser(): FormatStringExpressionParser;
13
- }
14
- export declare class FormatStringExpressionParser extends AbstractFormatExpressionParser<FormatStringExpression, ShorthandExpression | EvaluatedExpression> {
15
- private readonly placeholders;
16
- protected parsePlaceholder(source: ExpressionSource, start: number): EvaluatedExpression | ShorthandExpression<import("../shorthand/ShorthandExpression").ShorthandExpressionOptions>;
17
- protected createExpression(options: AbstractFormatExpressionOptions<ShorthandExpression | EvaluatedExpression>): FormatStringExpression;
18
- }
@@ -1,9 +0,0 @@
1
- export * from './ExpressionParser';
2
- export * from './CombinedParser';
3
- export * from './utils/parserUtils';
4
- export * from './code-parsers/CodeParser';
5
- export * from './code-parsers/JavaScriptParser';
6
- export { formatValue, formatValueAsync } from './utils/valueFormatting';
7
- export * from './expressions';
8
- export * from './definitions/ValidationContext';
9
- export * from './tokens';
@@ -1,12 +0,0 @@
1
- /**
2
- * A source node. Containers expose their children and assemble their source recursively.
3
- */
4
- export declare abstract class AbstractToken {
5
- readonly start: number;
6
- protected constructor(start?: number);
7
- abstract clone(): AbstractToken;
8
- get children(): readonly AbstractToken[];
9
- get end(): number;
10
- raw(): string;
11
- }
12
- export type ExpressionSource = string | readonly AbstractToken[];