+1

.gitignore

··· 1 1 + node_modules

+313

.kiro/specs/tagged-string/design.md

··· 1 1 + # Design Document 2 2 + 3 3 + ## Overview 4 4 + 5 5 + The Tagged String library is a simple, zero-dependency TypeScript library that extracts tagged entities from strings. The design focuses on simplicity and minimal API surface while providing flexible configuration options. 6 6 + 7 7 + **Example Usage:** 8 8 + ```typescript 9 9 + import chalk from 'chalk'; // Example formatter (not a dependency of parser) 10 10 + 11 11 + // Define schema for known entity types with formatters 12 12 + const schema = { 13 13 + operation: { type: 'string', format: chalk.yellow }, 14 14 + stack: { type: 'string', format: chalk.blue }, 15 15 + changes: { type: 'number', format: (n) => chalk.green(n.toString()) }, 16 16 + create: 'number', // Can use shorthand without formatter 17 17 + update: 'number', 18 18 + destroy: 'number' 19 19 + }; 20 20 + 21 21 + const parser = new TaggedStringParser({ schema }); 22 22 + const result = parser.parse('[operation:OP-123] started with [changes:5] to [stack:ST-456]'); 23 23 + 24 24 + // Access parsed entities 25 25 + // result.entities: [ 26 26 + // { type: 'operation', value: 'OP-123', parsedValue: 'OP-123', formattedValue: '\x1b[33mOP-123\x1b[39m', inferredType: 'string', position: 0 }, 27 27 + // { type: 'changes', value: '5', parsedValue: 5, formattedValue: '\x1b[32m5\x1b[39m', inferredType: 'number', position: 32 }, 28 28 + // { type: 'stack', value: 'ST-456', parsedValue: 'ST-456', formattedValue: '\x1b[34mST-456\x1b[39m', inferredType: 'string', position: 48 } 29 29 + // ] 30 30 + 31 31 + // Get formatted message with all entities formatted 32 32 + console.log(result.format()); 33 33 + // Output: "\x1b[33mOP-123\x1b[39m started with \x1b[32m5\x1b[39m to \x1b[34mST-456\x1b[39m" 34 34 + 35 35 + // Unknown entity types are automatically inferred (no formatting) 36 36 + const result2 = parser.parse('[count:42] [enabled:true] [name:test]'); 37 37 + // result2.entities: [ 38 38 + // { type: 'count', value: '42', parsedValue: 42, formattedValue: '42', inferredType: 'number', position: 0 }, 39 39 + // { type: 'enabled', value: 'true', parsedValue: true, formattedValue: 'true', inferredType: 'boolean', position: 11 }, 40 40 + // { type: 'name', value: 'test', parsedValue: 'test', formattedValue: 'test', inferredType: 'string', position: 26 } 41 41 + // ] 42 42 + 43 43 + // Filter by type 44 44 + result.getEntitiesByType('operation'); // [{ type: 'operation', value: 'OP-123', ... }] 45 45 + 46 46 + // Get all types 47 47 + result.getAllTypes(); // ['operation', 'changes', 'stack'] 48 48 + ``` 49 49 + 50 50 + ## Architecture 51 51 + 52 52 + The parser follows a simple single-pass scanning architecture: 53 53 + 54 54 + 1. **Input**: Raw string + optional configuration 55 55 + 2. **Scanning**: Character-by-character traversal identifying tag boundaries 56 56 + 3. **Extraction**: Parse entity type and value from tag content 57 57 + 4. **Output**: Collection of parsed entities with original message preserved 58 58 + 59 59 + The design uses a state machine approach during scanning to track whether the parser is inside or outside a tag. 60 60 + 61 61 + ## Components and Interfaces 62 62 + 63 63 + ### Entity Interface 64 64 + ```typescript 65 65 + interface Entity { 66 66 + type: string; // Entity type name (e.g., 'operation', 'count') 67 67 + value: string; // Raw string value from tag 68 68 + parsedValue: string | number | boolean; // Typed value based on schema or inference 69 69 + formattedValue: string; // Formatted string (via formatter or toString of parsedValue) 70 70 + inferredType: 'string' | 'number' | 'boolean'; // The determined type 71 71 + position: number; // Character position in original string 72 72 + } 73 73 + ``` 74 74 + 75 75 + ### EntitySchema Type 76 76 + ```typescript 77 77 + type PrimitiveType = 'string' | 'number' | 'boolean'; 78 78 + 79 79 + interface EntityDefinition { 80 80 + type: PrimitiveType; 81 81 + format?: (value: any) => string; // Optional formatter function 82 82 + } 83 83 + 84 84 + type EntitySchema = Record<string, PrimitiveType | EntityDefinition>; 85 85 + ``` 86 86 + 87 87 + ### ParserConfig Interface 88 88 + ```typescript 89 89 + interface ParserConfig { 90 90 + openDelimiter?: string; // Default: '[' 91 91 + closeDelimiter?: string; // Default: ']' 92 92 + typeSeparator?: string; // Default: ':' 93 93 + schema?: EntitySchema; // Optional schema for known entity types 94 94 + } 95 95 + ``` 96 96 + 97 97 + ### ParseResult Interface 98 98 + ```typescript 99 99 + interface ParseResult { 100 100 + originalMessage: string; 101 101 + entities: Entity[]; 102 102 + 103 103 + // Utility methods 104 104 + getEntitiesByType(type: string): Entity[]; 105 105 + getAllTypes(): string[]; 106 106 + format(): string; // Returns message with all entities replaced by their formattedValue 107 107 + } 108 108 + ``` 109 109 + 110 110 + ### TaggedStringParser Class 111 111 + ```typescript 112 112 + class TaggedStringParser { 113 113 + constructor(config?: ParserConfig); 114 114 + parse(message: string): ParseResult; 115 115 + 116 116 + // Internal helper methods 117 117 + private parseValue(type: string, rawValue: string): { 118 118 + parsedValue: string | number | boolean, 119 119 + formattedValue: string, 120 120 + inferredType: 'string' | 'number' | 'boolean' 121 121 + }; 122 122 + private inferType(value: string): 'string' | 'number' | 'boolean'; 123 123 + private applyFormatter(type: string, parsedValue: any): string; 124 124 + } 125 125 + ``` 126 126 + 127 127 + ## Data Models 128 128 + 129 129 + ### Internal Scanner State 130 130 + The parser maintains minimal state during scanning: 131 131 + - Current position in string 132 132 + - Whether currently inside a tag 133 133 + - Current tag content buffer 134 134 + - Accumulated entities array 135 135 + 136 136 + ### Entity Representation 137 137 + Entities are plain objects with six properties: 138 138 + - `type`: The classification/name of the entity (e.g., 'operation', 'count') 139 139 + - `value`: The raw string value extracted from the tag 140 140 + - `parsedValue`: The typed value (string, number, or boolean) based on schema or inference 141 141 + - `formattedValue`: The string representation after applying formatter (or toString of parsedValue) 142 142 + - `inferredType`: The determined primitive type 143 143 + - `position`: Where in the original string the tag started (useful for debugging) 144 144 + 145 145 + ### Schema, Type Inference, and Formatting 146 146 + The parser supports three layers of entity processing: 147 147 + 148 148 + 1. **Schema-based Type Parsing (Known Entities)**: When a schema is provided and an entity type matches a schema key, the parser uses the schema's specified type to parse the value. 149 149 + 150 150 + 2. **Inference-based Type Parsing (Unknown Entities)**: When no schema is provided or an entity type is not in the schema, the parser automatically infers the type: 151 151 + - Numbers: Values matching `/^-?\d+(\.\d+)?$/` are parsed as numbers 152 152 + - Booleans: Values matching `true` or `false` (case-insensitive) are parsed as booleans 153 153 + - Strings: Everything else defaults to string type 154 154 + 155 155 + 3. **Formatting**: After parsing, entities can be formatted: 156 156 + - If a formatter function is provided in the schema, it's applied to the parsedValue 157 157 + - If no formatter is provided, the parsedValue is converted to string 158 158 + - The formattedValue is used when calling `result.format()` to reconstruct the message 159 159 + 160 160 + This three-layer approach allows users to: 161 161 + - Define expected entity types explicitly 162 162 + - Handle ad-hoc entities automatically 163 163 + - Apply custom formatting (colors, trimming, etc.) per entity type 164 164 + 165 165 + ## Error Handling 166 166 + 167 167 + The parser follows a lenient error handling strategy: 168 168 + 169 169 + 1. **Malformed Tags**: Skip and continue parsing 170 170 + - Unclosed tags: Ignore the incomplete tag 171 171 + - Missing type separator: Treat entire content as value with empty type 172 172 + - Empty tags: Skip entirely 173 173 + 174 174 + 2. **Invalid Configuration**: Throw errors during construction 175 175 + - Empty delimiters 176 176 + - Delimiter conflicts (open === close) 177 177 + - Multi-character delimiters that could cause ambiguity 178 178 + 179 179 + 3. **Edge Cases**: 180 180 + - Empty strings: Return empty entity array 181 181 + - Nested tags: Not supported, inner delimiters treated as literal characters 182 182 + - Escaped delimiters: Not supported in v1 (future enhancement) 183 183 + 184 184 + ## Testing Strategy 185 185 + 186 186 + ### Unit Tests 187 187 + Focus on core parsing logic: 188 188 + - Single entity extraction 189 189 + - Multiple entities in one message 190 190 + - Messages without entities 191 191 + - Malformed tag handling 192 192 + - Custom delimiter configuration 193 193 + - Entity ordering preservation 194 194 + - Type-based filtering 195 195 + - Schema-based type parsing 196 196 + - Automatic type inference for unknown entities 197 197 + - Number, boolean, and string type detection 198 198 + 199 199 + ### Test Structure 200 200 + ```typescript 201 201 + describe('TaggedStringParser', () => { 202 202 + describe('parse', () => { 203 203 + it('should extract single entity'); 204 204 + it('should extract multiple entities'); 205 205 + it('should handle messages without entities'); 206 206 + it('should skip malformed tags'); 207 207 + it('should preserve entity order'); 208 208 + }); 209 209 + 210 210 + describe('schema and type inference', () => { 211 211 + it('should parse known entities using schema'); 212 212 + it('should infer number type for numeric values'); 213 213 + it('should infer boolean type for true/false values'); 214 214 + it('should default to string type for other values'); 215 215 + it('should handle mixed known and unknown entities'); 216 216 + }); 217 217 + 218 218 + describe('configuration', () => { 219 219 + it('should use custom delimiters'); 220 220 + it('should throw on invalid config'); 221 221 + }); 222 222 + 223 223 + describe('ParseResult', () => { 224 224 + it('should filter entities by type'); 225 225 + it('should return all entity types'); 226 226 + }); 227 227 + }); 228 228 + ``` 229 229 + 230 230 + ## Real-World Examples 231 231 + 232 232 + Based on IaC system logging patterns: 233 233 + 234 234 + ```typescript 235 235 + // Operation lifecycle 236 236 + parser.parse('[operation:OP-123] started with [changes:5] to [stack:ST-456]'); 237 237 + parser.parse('[operation:OP-123] completed [changes:5] to [stack:ST-456]'); 238 238 + parser.parse('[operation:OP-123] failed: [reason:"Error message"]'); 239 239 + 240 240 + // Planning 241 241 + parser.parse('[blueprint:BP-123] planning for [stack:ST-456]'); 242 242 + parser.parse('[blueprint:BP-123] plan complete with [create:2] [update:3] [destroy:1] for [stack:ST-456]'); 243 243 + 244 244 + // Resource commands 245 245 + parser.parse('[action:create] executing for [resource:RS-123] [resourceName:"my-function"] [type:function]'); 246 246 + parser.parse('[action:create] completed for [resource:RS-123] [externalId:EXT-789]'); 247 247 + parser.parse('[action:create] failed for [resource:RS-123]: [error:"Error message"]'); 248 248 + 249 249 + // Resource type-specific 250 250 + parser.parse('[resourceType:function] creating [resourceName:"my-function"]'); 251 251 + parser.parse('[resourceType:database] updating [resourceName:"user-db"]'); 252 252 + ``` 253 253 + 254 254 + ### Handling Quoted Values 255 255 + Note that values may contain quotes (e.g., `[resourceName:"my-function"]`). The parser treats everything between the type separator and closing delimiter as the value, including quotes. This keeps the implementation simple while preserving the original data format. 256 256 + 257 257 + ## Runtime Environment 258 258 + 259 259 + ### Node.js v24 Native TypeScript Support 260 260 + The parser is designed to run directly with Node.js v24's native TypeScript execution: 261 261 + 262 262 + ```bash 263 263 + # Run directly without compilation 264 264 + node --experimental-strip-types parser.ts 265 265 + 266 266 + # Or with the simpler flag (Node v24+) 267 267 + node parser.ts 268 268 + ``` 269 269 + 270 270 + No build step or compilation to JavaScript is required. The parser can be developed and executed as pure TypeScript files. 271 271 + 272 272 + ## Implementation Notes 273 273 + 274 274 + ### Performance Considerations 275 275 + - Single-pass parsing: O(n) time complexity 276 276 + - Type inference uses simple string checks (no regex for numbers/booleans) 277 277 + - Minimal memory allocation (reuse buffers where possible) 278 278 + - Schema lookup is O(1) using object property access 279 279 + 280 280 + ### Design Decisions 281 281 + 282 282 + **Why character-by-character scanning?** 283 283 + - Simpler to understand and maintain 284 284 + - No regex complexity 285 285 + - Easier to handle edge cases 286 286 + - Predictable performance 287 287 + 288 288 + **Why lenient error handling?** 289 289 + - Strings should never break parsing 290 290 + - Partial data is better than no data 291 291 + - Aligns with robustness principle: "Be liberal in what you accept" 292 292 + 293 293 + **Why include position in Entity?** 294 294 + - Useful for debugging 295 295 + - Minimal overhead 296 296 + - Enables future features (e.g., highlighting in UI) 297 297 + 298 298 + **Why no nested tag support?** 299 299 + - Keeps implementation simple 300 300 + - Rare use case for strings 301 301 + - Can be added later if needed 302 302 + 303 303 + **Why both schema and inference?** 304 304 + - Schema provides explicit control for important entity types 305 305 + - Inference handles ad-hoc entities without configuration 306 306 + - Consumers get typed values for better formatting control 307 307 + - Balances flexibility with type safety 308 308 + 309 309 + **Why Node v24 without compilation?** 310 310 + - Faster development iteration (no build step) 311 311 + - Simpler project setup 312 312 + - Native TypeScript support is stable in Node v24 313 313 + - Reduces tooling complexity

+89

.kiro/specs/tagged-string/requirements.md

··· 1 1 + # Requirements Document 2 2 + 3 3 + ## Introduction 4 4 + 5 5 + The Tagged String library is a lightweight TypeScript string parsing library with zero dependencies. It extracts structured entity information from strings using a tag-based syntax. The parser identifies and extracts tagged entities (such as data models, counts, identifiers, and other structured data) from strings, making them programmatically accessible while maintaining the readability of the original message. 6 6 + 7 7 + ## Glossary 8 8 + 9 9 + - **Parser**: The system component that processes input strings and extracts tagged entities 10 10 + - **Entity**: A structured piece of information embedded in a string using tag syntax 11 11 + - **Tag**: A syntactic marker that identifies the start and type of an entity within a string 12 12 + - **String**: A human-readable string that may contain zero or more tagged entities 13 13 + - **Entity Type**: A classification label for an entity (e.g., model, count, identifier) 14 14 + - **Schema**: A user-defined specification that maps entity type names to their expected data types 15 15 + - **Known Entity**: An entity whose type is defined in the parser's schema 16 16 + - **Unknown Entity**: An entity whose type is not defined in the schema, requiring automatic type inference 17 17 + - **Primitive Type**: A basic data type (string, number, boolean) inferred from entity values 18 18 + 19 19 + ## Requirements 20 20 + 21 21 + ### Requirement 1 22 22 + 23 23 + **User Story:** As a developer, I want to parse tagged entities from strings, so that I can extract structured data while keeping strings human-readable 24 24 + 25 25 + #### Acceptance Criteria 26 26 + 27 27 + 1. WHEN the Parser receives a string containing tagged entities, THE Parser SHALL extract all entities with their type and value 28 28 + 2. WHEN the Parser receives a string without any tagged entities, THE Parser SHALL return an empty entity collection 29 29 + 3. THE Parser SHALL preserve the original string text during parsing 30 30 + 4. THE Parser SHALL support multiple entities within a single string 31 31 + 5. WHEN the Parser encounters malformed tag syntax, THE Parser SHALL skip the malformed tag and continue parsing 32 32 + 33 33 + ### Requirement 2 34 34 + 35 35 + **User Story:** As a developer, I want to define custom tag syntax, so that I can adapt the parser to different conventions 36 36 + 37 37 + #### Acceptance Criteria 38 38 + 39 39 + 1. THE Parser SHALL accept configuration for tag opening delimiter 40 40 + 2. THE Parser SHALL accept configuration for tag closing delimiter 41 41 + 3. THE Parser SHALL accept configuration for type-value separator syntax 42 42 + 4. WHEN no configuration is provided, THE Parser SHALL use default tag syntax 43 43 + 5. THE Parser SHALL validate configuration parameters before parsing 44 44 + 45 45 + ### Requirement 3 46 46 + 47 47 + **User Story:** As a developer, I want to access parsed entities by type, so that I can easily retrieve specific kinds of information from strings 48 48 + 49 49 + #### Acceptance Criteria 50 50 + 51 51 + 1. THE Parser SHALL provide a method to retrieve all entities of a specific type 52 52 + 2. THE Parser SHALL provide a method to retrieve all parsed entities 53 53 + 3. THE Parser SHALL return entities in the order they appear in the string 54 54 + 4. WHEN no entities of a requested type exist, THE Parser SHALL return an empty collection 55 55 + 56 56 + ### Requirement 4 57 57 + 58 58 + **User Story:** As a developer, I want to define a schema for known entity types, so that the parser can provide typed values for entities I care about 59 59 + 60 60 + #### Acceptance Criteria 61 61 + 62 62 + 1. THE Parser SHALL accept an optional schema mapping entity type names to expected data types 63 63 + 2. WHEN the Parser encounters a Known Entity, THE Parser SHALL parse the value according to the schema type 64 64 + 3. WHEN the Parser encounters an Unknown Entity, THE Parser SHALL infer the primitive type from the value 65 65 + 4. THE Parser SHALL support string, number, and boolean primitive types for Unknown Entities 66 66 + 5. THE Parser SHALL expose typed values to consumers for programmatic formatting 67 67 + 68 68 + ### Requirement 5 69 69 + 70 70 + **User Story:** As a developer, I want to apply custom formatters to entity values, so that I can control how entities are displayed in output 71 71 + 72 72 + #### Acceptance Criteria 73 73 + 74 74 + 1. THE Parser SHALL accept optional formatter functions in the schema for each entity type 75 75 + 2. WHEN a formatter is provided for an entity type, THE Parser SHALL apply the formatter to the parsed value 76 76 + 3. WHEN no formatter is provided, THE Parser SHALL convert the parsed value to string 77 77 + 4. THE Parser SHALL store the formatted result in the Entity formattedValue property 78 78 + 5. THE Parser SHALL provide a format method on ParseResult that reconstructs the message with formatted entities 79 79 + 80 80 + ### Requirement 6 81 81 + 82 82 + **User Story:** As a developer, I want the parser to have zero runtime dependencies and run directly with Node.js, so that I can use it without compilation overhead 83 83 + 84 84 + #### Acceptance Criteria 85 85 + 86 86 + 1. THE Parser SHALL be implemented using only TypeScript standard library features 87 87 + 2. THE Parser SHALL not require any third-party runtime dependencies 88 88 + 3. THE Parser SHALL be executable directly with Node.js v24 native TypeScript support 89 89 + 4. THE Parser SHALL not require compilation to JavaScript for execution

+121

.kiro/specs/tagged-string/tasks.md

··· 1 1 + # Implementation Plan 2 2 + 3 3 + - [x] 1. Set up project structure and type definitions 4 4 + - Create TypeScript configuration file (tsconfig.json) for Node v24 native execution 5 5 + - Define Entity interface with type, value, parsedValue, formattedValue, inferredType, and position properties 6 6 + - Define PrimitiveType and EntityDefinition types for schema with optional formatters 7 7 + - Define EntitySchema type for mapping entity types to primitive types or definitions with formatters 8 8 + - Define ParserConfig interface with delimiter, separator, and schema options 9 9 + - Define ParseResult interface with utility methods including format() 10 10 + - _Requirements: 6.1, 6.2, 6.3, 6.4_ 11 11 + 12 12 + - [x] 2. Implement ParseResult class 13 13 + - [x] 2.1 Create ParseResult class with constructor accepting original message and entities array 14 14 + - Store original message and entities as properties 15 15 + - _Requirements: 1.3_ 16 16 + 17 17 + - [x] 2.2 Implement getEntitiesByType method 18 18 + - Filter entities array by type parameter 19 19 + - Return filtered array in original order 20 20 + - Return empty array when no matches found 21 21 + - _Requirements: 3.1, 3.2, 3.3, 3.4_ 22 22 + 23 23 + - [x] 2.3 Implement getAllTypes method 24 24 + - Extract unique entity types from entities array 25 25 + - Return array of type strings 26 26 + - _Requirements: 3.2_ 27 27 + 28 28 + - [x] 2.4 Implement format method 29 29 + - Reconstruct original message replacing tags with formattedValue from entities 30 30 + - Use entity position to correctly place formatted values 31 31 + - Return formatted string 32 32 + - _Requirements: 5.5_ 33 33 + 34 34 + - [x] 3. Implement TaggedStringParser class 35 35 + - [x] 3.1 Create parser class with configuration support 36 36 + - Accept optional ParserConfig in constructor (including schema) 37 37 + - Set default delimiters: '[' and ']' 38 38 + - Set default type separator: ':' 39 39 + - Store schema for entity type lookup 40 40 + - Validate configuration (no empty delimiters, no delimiter conflicts) 41 41 + - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 4.1, 5.1_ 42 42 + 43 43 + - [x] 3.2 Implement type inference and parsing helpers 44 44 + - Create inferType method to detect number, boolean, or string from raw value 45 45 + - Create parseValue method that uses schema (if available) or falls back to inference 46 46 + - Handle number parsing (including decimals and negatives) 47 47 + - Handle boolean parsing (case-insensitive true/false) 48 48 + - Default to string for all other values 49 49 + - _Requirements: 4.2, 4.3, 4.4, 4.5_ 50 50 + 51 51 + - [x] 3.3 Implement formatter application 52 52 + - Create applyFormatter method that checks schema for formatter function 53 53 + - If formatter exists, apply it to parsedValue and return result 54 54 + - If no formatter, convert parsedValue to string 55 55 + - Store result as formattedValue in entity 56 56 + - _Requirements: 5.1, 5.2, 5.3, 5.4_ 57 57 + 58 58 + - [x] 3.4 Implement core parsing logic in parse method 59 59 + - Create character-by-character scanner 60 60 + - Track parser state (inside/outside tag) 61 61 + - Accumulate tag content when inside tag boundaries 62 62 + - Extract entity type and raw value from tag content using separator 63 63 + - Call parseValue to get typed parsedValue and inferredType 64 64 + - Call applyFormatter to get formattedValue 65 65 + - Record entity position in original string 66 66 + - Handle malformed tags by skipping and continuing 67 67 + - Return ParseResult with original message and extracted entities 68 68 + - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 3.3, 4.2, 4.5, 5.4_ 69 69 + 70 70 + - [x] 3.5 Handle edge cases in parsing 71 71 + - Return empty entities array for empty input strings 72 72 + - Skip unclosed tags at end of string 73 73 + - Handle tags without type separator (treat as value with empty type) 74 74 + - Skip empty tags 75 75 + - Preserve quoted values in entity values 76 76 + - _Requirements: 1.2, 1.5_ 77 77 + 78 78 + - [x] 4. Write unit tests for ParseResult 79 79 + - Test getEntitiesByType with matching and non-matching types 80 80 + - Test getAllTypes with multiple and zero entities 81 81 + - Test entity order preservation 82 82 + - Test format method reconstructs message with formatted entities 83 83 + - Test format method with entities that have custom formatters 84 84 + - _Requirements: 3.1, 3.2, 3.3, 3.4, 5.5_ 85 85 + 86 86 + - [x] 5. Write unit tests for TaggedStringParser 87 87 + - Test single entity extraction 88 88 + - Test multiple entities in one message 89 89 + - Test messages without entities 90 90 + - Test custom delimiter configuration 91 91 + - Test configuration validation (invalid delimiters) 92 92 + - Test malformed tag handling (unclosed, missing separator, empty) 93 93 + - Test entity position tracking 94 94 + - Test schema-based type parsing for known entities 95 95 + - Test automatic type inference for unknown entities (numbers, booleans, strings) 96 96 + - Test mixed known and unknown entities in same message 97 97 + - Test formatter functions applied to entity values 98 98 + - Test entities without formatters default to string conversion 99 99 + - Test shorthand schema syntax (just type) vs full EntityDefinition with formatter 100 100 + - Test real-world IaC log examples from design document 101 101 + - _Requirements: 1.1, 1.2, 1.4, 1.5, 2.1, 2.2, 2.3, 2.4, 2.5, 4.2, 4.3, 4.4, 4.5, 5.1, 5.2, 5.3, 5.4_ 102 102 + 103 103 + - [x] 6. Create example usage file 104 104 + - Create examples.ts demonstrating basic usage with schema 105 105 + - Show schema definition for known entity types with formatters 106 106 + - Include example with chalk or simple string formatters (String.trim, toUpperCase, etc.) 107 107 + - Include IaC logging examples from design document 108 108 + - Show custom configuration usage 109 109 + - Show entity filtering by type 110 110 + - Demonstrate accessing parsedValue, formattedValue, and inferredType properties 111 111 + - Show examples of automatic type inference for unknown entities 112 112 + - Demonstrate format() method to get fully formatted message 113 113 + - _Requirements: 1.1, 2.1, 3.1, 4.2, 4.5, 5.1, 5.5_ 114 114 + 115 115 + - [x] 7. Create package.json and Node v24 configuration 116 116 + - Set up package.json with TypeScript as dev dependency only 117 117 + - Configure for Node v24 native TypeScript execution 118 118 + - Add script to run examples directly without compilation 119 119 + - Set module type and entry points 120 120 + - Verify zero runtime dependencies 121 121 + - _Requirements: 6.1, 6.2, 6.3, 6.4_

+15

.kiro/steering/product.md

··· 1 1 + # Product Overview 2 2 + 3 3 + Tagged String is a lightweight, zero-dependency TypeScript library for extracting structured entity information from strings using tag-based syntax (e.g., `[operation:OP-123]`). 4 4 + 5 5 + ## Core Purpose 6 6 + 7 7 + Parse tagged entities from strings while maintaining readability, enabling programmatic access to structured data embedded in text. Designed for IaC systems and other applications that need to extract typed information from string output. 8 8 + 9 9 + ## Key Features 10 10 + 11 11 + - Tag-based entity extraction with configurable delimiters 12 12 + - Schema-based type parsing for known entities with optional formatters 13 13 + - Automatic type inference (string, number, boolean) for unknown entities 14 14 + - Entity filtering and message reconstruction with formatted values 15 15 + - Zero runtime dependencies, runs natively on Node.js v24

+43

.kiro/steering/structure.md

··· 1 1 + # Project Structure 2 2 + 3 3 + ## Directory Layout 4 4 + 5 5 + ``` 6 6 + . 7 7 + ├── .kiro/ 8 8 + │ ├── specs/ # Feature specifications (requirements, design, tasks) 9 9 + │ └── steering/ # AI assistant guidance documents 10 10 + ├── src/ 11 11 + │ └── types.ts # Core type definitions and interfaces 12 12 + ├── dist/ # Compiled output (generated) 13 13 + ├── TODO.md # Project task list (keep updated) 14 14 + └── tsconfig.json # TypeScript configuration 15 15 + ``` 16 16 + 17 17 + ## Code Organization 18 18 + 19 19 + ### Type Definitions (`src/types.ts`) 20 20 + 21 21 + Central location for all TypeScript interfaces and types: 22 22 + - `PrimitiveType`: Supported primitive types (string, number, boolean) 23 23 + - `EntityDefinition`: Entity schema with optional formatter 24 24 + - `EntitySchema`: Schema mapping for entity types 25 25 + - `Entity`: Parsed entity structure with type, value, parsedValue, formattedValue, inferredType, position 26 26 + - `ParserConfig`: Parser configuration options 27 27 + - `ParseResult`: Parse result with utility methods 28 28 + 29 29 + ### Implementation Files (to be created) 30 30 + 31 31 + - Parser class implementation 32 32 + - ParseResult class implementation 33 33 + - Helper functions for type inference and formatting 34 34 + 35 35 + ## Conventions 36 36 + 37 37 + - All interfaces and types defined before implementation 38 38 + - Comprehensive JSDoc comments on public interfaces 39 39 + - Single-pass parsing architecture 40 40 + - Lenient error handling (skip malformed input, don't throw) 41 41 + - Position tracking for all extracted entities 42 42 + - Keep TODO.md updated with current tasks and progress 43 43 + - Add issues, bugs, and important features to TODO.md when discovered

+29

.kiro/steering/tech.md

··· 1 1 + # Technology Stack 2 2 + 3 3 + ## Runtime 4 4 + 5 5 + - **Node.js**: v24+ with native TypeScript support 6 6 + - **Dependencies**: Zero runtime dependencies (core principle) 7 7 + 8 8 + ## TS Configuration 9 9 + 10 10 + - **Target**: ES2022 11 11 + - **Module System**: ESNext with Node resolution 12 12 + - **Strict Mode**: Enabled for type safety 13 13 + 14 14 + ## Common Commands 15 15 + 16 16 + ```bash 17 17 + # Run tests; no flags required 18 18 + npm t 19 19 + 20 20 + # Run TypeScript directly (Node v24+) 21 21 + node src/parser.ts 22 22 + ``` 23 23 + 24 24 + ## Development Principles 25 25 + 26 26 + - No third-party runtime dependencies 27 27 + - Direct TypeScript execution without build step during development 28 28 + - TypeScript standard library only 29 29 + - Simple, maintainable implementations over complex optimizations

+177

README.md

··· 1 1 + # Tagged String 2 2 + 3 3 + Extract structured data from strings using tag-based syntax. Zero dependencies, runs natively on Node.js v24+. 4 4 + 5 5 + ```typescript 6 6 + import { TaggedStringParser } from 'tagged-string'; 7 7 + 8 8 + const parser = new TaggedStringParser(); 9 9 + const result = parser.parse('[operation:deploy] started with [changes:5] to [stack:prod-stack]'); 10 10 + 11 11 + console.log(result.entities); 12 12 + // [ 13 13 + // { type: 'operation', value: 'deploy', parsedValue: 'deploy', inferredType: 'string', ... }, 14 14 + // { type: 'changes', value: '5', parsedValue: 5, inferredType: 'number', ... }, 15 15 + // { type: 'stack', value: 'prod-stack', parsedValue: 'prod-stack', inferredType: 'string', ... } 16 16 + // ] 17 17 + ``` 18 18 + 19 19 + ## Installation 20 20 + 21 21 + ```bash 22 22 + npm install tagged-string 23 23 + ``` 24 24 + 25 25 + Requires Node.js v24 or later for native TypeScript support. 26 26 + 27 27 + ## Usage 28 28 + 29 29 + ### Basic Parsing 30 30 + 31 31 + The parser extracts `[type:value]` tags from strings and automatically infers types: 32 32 + 33 33 + ```typescript 34 34 + const parser = new TaggedStringParser(); 35 35 + const result = parser.parse('[count:42] items processed, [enabled:true] flag set'); 36 36 + 37 37 + result.entities.forEach(entity => { 38 38 + console.log(entity.type, entity.parsedValue, entity.inferredType); 39 39 + }); 40 40 + // count 42 number 41 41 + // enabled true boolean 42 42 + ``` 43 43 + 44 44 + ### Schema-Based Parsing 45 45 + 46 46 + Define a schema to enforce types and add formatters: 47 47 + 48 48 + ```typescript 49 49 + const parser = new TaggedStringParser({ 50 50 + schema: { 51 51 + operation: { type: 'string', format: (v) => v.toUpperCase() }, 52 52 + changes: { type: 'number', format: (n) => `${n} changes` }, 53 53 + stack: 'string', // shorthand without formatter 54 54 + } 55 55 + }); 56 56 + 57 57 + const result = parser.parse('[operation:deploy] started with [changes:5] to [stack:prod-stack]'); 58 58 + console.log(result.format()); 59 59 + // "DEPLOY started with 5 changes to prod-stack" 60 60 + ``` 61 61 + 62 62 + ### Filtering Entities 63 63 + 64 64 + ```typescript 65 65 + const result = parser.parse('[action:create] [resource:function] with [count:3] instances'); 66 66 + 67 67 + result.getEntitiesByType('action'); // [{ type: 'action', parsedValue: 'create', ... }] 68 68 + result.getAllTypes(); // ['action', 'resource', 'count'] 69 69 + ``` 70 70 + 71 71 + ### Custom Delimiters 72 72 + 73 73 + ```typescript 74 74 + const parser = new TaggedStringParser({ 75 75 + openDelimiter: '{{', 76 76 + closeDelimiter: '}}', 77 77 + typeSeparator: '=', 78 78 + schema: { 79 79 + user: { type: 'string', format: (v) => `@${v}` } 80 80 + } 81 81 + }); 82 82 + 83 83 + const result = parser.parse('User {{user=john}} performed {{count=10}} actions'); 84 84 + console.log(result.format()); 85 85 + // "User @john performed 10 actions" 86 86 + ``` 87 87 + 88 88 + ## API 89 89 + 90 90 + ### `TaggedStringParser` 91 91 + 92 92 + ```typescript 93 93 + constructor(config?: ParserConfig) 94 94 + ``` 95 95 + 96 96 + **Config options:** 97 97 + - `openDelimiter` (default: `'['`) - Opening tag delimiter 98 98 + - `closeDelimiter` (default: `']'`) - Closing tag delimiter 99 99 + - `typeSeparator` (default: `':'`) - Separator between type and value 100 100 + - `schema` - Entity type definitions with optional formatters 101 101 + 102 102 + ```typescript 103 103 + parse(message: string): ParseResult 104 104 + ``` 105 105 + 106 106 + Extracts all tagged entities from the message. 107 107 + 108 108 + ### `ParseResult` 109 109 + 110 110 + **Properties:** 111 111 + - `originalMessage: string` - The input message 112 112 + - `entities: Entity[]` - Extracted entities in order 113 113 + 114 114 + **Methods:** 115 115 + - `getEntitiesByType(type: string): Entity[]` - Filter entities by type 116 116 + - `getAllTypes(): string[]` - Get unique entity types 117 117 + - `format(): string` - Reconstruct message with formatted values 118 118 + 119 119 + ### `Entity` 120 120 + 121 121 + ```typescript 122 122 + interface Entity { 123 123 + type: string; // Entity type name 124 124 + value: string; // Raw string value 125 125 + parsedValue: string | number | boolean; // Typed value 126 126 + formattedValue: string; // Formatted display value 127 127 + inferredType: 'string' | 'number' | 'boolean'; 128 128 + position: number; // Start position in message 129 129 + endPosition: number; // End position in message 130 130 + } 131 131 + ``` 132 132 + 133 133 + ### `EntitySchema` 134 134 + 135 135 + ```typescript 136 136 + type EntitySchema = Record<string, PrimitiveType | EntityDefinition>; 137 137 + 138 138 + interface EntityDefinition { 139 139 + type: 'string' | 'number' | 'boolean'; 140 140 + format?: (value: any) => string; 141 141 + } 142 142 + ``` 143 143 + 144 144 + ## Type Inference 145 145 + 146 146 + Without a schema, the parser infers types automatically: 147 147 + 148 148 + - **number**: Matches `/^-?\d+(\.\d+)?$/` (integers and decimals) 149 149 + - **boolean**: `'true'` or `'false'` (case-insensitive) 150 150 + - **string**: Everything else 151 151 + 152 152 + ## Error Handling 153 153 + 154 154 + The parser is lenient by design: 155 155 + - Malformed tags are skipped 156 156 + - Unclosed tags at end of string are ignored 157 157 + - Empty tag content is skipped 158 158 + - Invalid config throws on construction 159 159 + 160 160 + ## Examples 161 161 + 162 162 + Run the included examples: 163 163 + 164 164 + ```bash 165 165 + node src/examples.ts 166 166 + ``` 167 167 + 168 168 + ## Development 169 169 + 170 170 + ```bash 171 171 + npm test # Run tests 172 172 + node src/examples.ts # Run examples 173 173 + ``` 174 174 + 175 175 + ## License 176 176 + 177 177 + MIT

+74

TODO.md

··· 1 1 + # TODO / Known Issues 2 2 + 3 3 + ## Known Limitations 4 4 + 5 5 + (No known limitations at this time) 6 6 + 7 7 + --- 8 8 + 9 9 + ## Recently Resolved 10 10 + 11 11 + ### ✅ ParseResult.format() doesn't support custom delimiters 12 12 + **Status:** RESOLVED 13 13 + **Resolved:** November 11, 2025 14 14 + **Solution:** Added `endPosition` field to Entity interface and updated format() method to use stored positions 15 15 + 16 16 + The `ParseResult.format()` method now correctly handles custom delimiters by storing the tag end position during parsing. The Entity interface was extended with an `endPosition` field, and the format() method uses this stored position instead of searching for hardcoded delimiters. 17 17 + 18 18 + **Implementation:** 19 19 + - Added `endPosition: number` to Entity interface 20 20 + - Modified TaggedStringParser to calculate and store tag end positions 21 21 + - Updated ParseResult.format() to use entity.endPosition 22 22 + - Added comprehensive tests for custom delimiter formatting 23 23 + - Updated examples to demonstrate custom delimiter usage 24 24 + 25 25 + --- 26 26 + 27 27 + ## Future Enhancements 28 28 + 29 29 + ### Nested Delimiter Support 30 30 + **Current behavior:** `[outer:[inner:value]]` extracts `[inner:value` as the value (stops at first closing delimiter) 31 31 + **Consideration:** Add support for properly parsing nested tags, either by: 32 32 + - Escaping inner delimiters 33 33 + - Counting delimiter depth 34 34 + - Supporting a different syntax for nested structures 35 35 + 36 36 + **Use case:** Complex structured data like `[config:{host:localhost,port:8080}]` 37 37 + 38 38 + ### Empty Type Handling 39 39 + **Current behavior:** `[:value]` works but creates entity with empty string type 40 40 + **Consideration:** Decide on explicit behavior: 41 41 + - Allow empty types as valid (current) 42 42 + - Treat as error/skip 43 43 + - Use a default type name like `"_default"` or `"value"` 44 44 + 45 45 + **Use case:** Quick tagging without type classification: `[:important]` or `[:TODO]` 46 46 + 47 47 + ### Multiple Separator Behavior 48 48 + **Current behavior:** `[type:value:extra]` splits on first `:` only, value becomes `value:extra` 49 49 + **Consideration:** Document this behavior explicitly or add options: 50 50 + - Split on first separator only (current, implicit) 51 51 + - Support escaped separators: `[type:value\:with\:colons]` 52 52 + - Allow configuration for multi-part values 53 53 + 54 54 + **Use case:** Values containing the separator character like URLs or timestamps 55 55 + 56 56 + ### NaN Handling for Invalid Numbers 57 57 + **Current behavior:** `[count:abc]` with `number` schema produces `NaN` as parsedValue 58 58 + **Consideration:** Add validation/error handling: 59 59 + - Throw error on invalid number 60 60 + - Fall back to string type 61 61 + - Add a `parseError` field to Entity 62 62 + - Provide a validation callback in schema 63 63 + 64 64 + **Use case:** Catching malformed numeric data early 65 65 + 66 66 + ### Formatter Error Handling 67 67 + **Current behavior:** If a custom formatter throws an error, parsing crashes 68 68 + **Consideration:** Make parsing more resilient: 69 69 + - Catch formatter errors and fall back to `String(value)` 70 70 + - Add error callback to config 71 71 + - Add `formatterError` field to Entity 72 72 + - Skip entities with formatter errors 73 73 + 74 74 + **Use case:** Robust parsing even with buggy custom formatters

+37

biome.json

··· 1 1 + { 2 2 + "$schema": "https://biomejs.dev/schemas/2.3.5/schema.json", 3 3 + "vcs": { 4 4 + "enabled": true, 5 5 + "clientKind": "git", 6 6 + "useIgnoreFile": true 7 7 + }, 8 8 + "files": { 9 9 + "ignoreUnknown": false 10 10 + }, 11 11 + "formatter": { 12 12 + "enabled": true, 13 13 + "indentStyle": "space", 14 14 + "indentWidth": 2 15 15 + }, 16 16 + "linter": { 17 17 + "enabled": true, 18 18 + "rules": { 19 19 + "recommended": true 20 20 + } 21 21 + }, 22 22 + "javascript": { 23 23 + "formatter": { 24 24 + "quoteStyle": "single", 25 25 + "trailingCommas": "all", 26 26 + "semicolons": "asNeeded" 27 27 + } 28 28 + }, 29 29 + "assist": { 30 30 + "enabled": true, 31 31 + "actions": { 32 32 + "source": { 33 33 + "organizeImports": "on" 34 34 + } 35 35 + } 36 36 + } 37 37 + }

+2

mise.toml

··· 1 1 + [tools] 2 2 + node = "24"

+215

package-lock.json

··· 1 1 + { 2 2 + "name": "tagged-string", 3 3 + "version": "0.0.0", 4 4 + "lockfileVersion": 3, 5 5 + "requires": true, 6 6 + "packages": { 7 7 + "": { 8 8 + "name": "tagged-string", 9 9 + "version": "0.0.0", 10 10 + "license": "MIT", 11 11 + "devDependencies": { 12 12 + "@biomejs/biome": "2.3.5", 13 13 + "@types/node": "^24.10.0", 14 14 + "typescript": "^5.7.2" 15 15 + }, 16 16 + "engines": { 17 17 + "node": ">=24.0.0" 18 18 + } 19 19 + }, 20 20 + "node_modules/@biomejs/biome": { 21 21 + "version": "2.3.5", 22 22 + "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.3.5.tgz", 23 23 + "integrity": "sha512-HvLhNlIlBIbAV77VysRIBEwp55oM/QAjQEin74QQX9Xb259/XP/D5AGGnZMOyF1el4zcvlNYYR3AyTMUV3ILhg==", 24 24 + "dev": true, 25 25 + "license": "MIT OR Apache-2.0", 26 26 + "bin": { 27 27 + "biome": "bin/biome" 28 28 + }, 29 29 + "engines": { 30 30 + "node": ">=14.21.3" 31 31 + }, 32 32 + "funding": { 33 33 + "type": "opencollective", 34 34 + "url": "https://opencollective.com/biome" 35 35 + }, 36 36 + "optionalDependencies": { 37 37 + "@biomejs/cli-darwin-arm64": "2.3.5", 38 38 + "@biomejs/cli-darwin-x64": "2.3.5", 39 39 + "@biomejs/cli-linux-arm64": "2.3.5", 40 40 + "@biomejs/cli-linux-arm64-musl": "2.3.5", 41 41 + "@biomejs/cli-linux-x64": "2.3.5", 42 42 + "@biomejs/cli-linux-x64-musl": "2.3.5", 43 43 + "@biomejs/cli-win32-arm64": "2.3.5", 44 44 + "@biomejs/cli-win32-x64": "2.3.5" 45 45 + } 46 46 + }, 47 47 + "node_modules/@biomejs/cli-darwin-arm64": { 48 48 + "version": "2.3.5", 49 49 + "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.3.5.tgz", 50 50 + "integrity": "sha512-fLdTur8cJU33HxHUUsii3GLx/TR0BsfQx8FkeqIiW33cGMtUD56fAtrh+2Fx1uhiCsVZlFh6iLKUU3pniZREQw==", 51 51 + "cpu": [ 52 52 + "arm64" 53 53 + ], 54 54 + "dev": true, 55 55 + "license": "MIT OR Apache-2.0", 56 56 + "optional": true, 57 57 + "os": [ 58 58 + "darwin" 59 59 + ], 60 60 + "engines": { 61 61 + "node": ">=14.21.3" 62 62 + } 63 63 + }, 64 64 + "node_modules/@biomejs/cli-darwin-x64": { 65 65 + "version": "2.3.5", 66 66 + "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.3.5.tgz", 67 67 + "integrity": "sha512-qpT8XDqeUlzrOW8zb4k3tjhT7rmvVRumhi2657I2aGcY4B+Ft5fNwDdZGACzn8zj7/K1fdWjgwYE3i2mSZ+vOA==", 68 68 + "cpu": [ 69 69 + "x64" 70 70 + ], 71 71 + "dev": true, 72 72 + "license": "MIT OR Apache-2.0", 73 73 + "optional": true, 74 74 + "os": [ 75 75 + "darwin" 76 76 + ], 77 77 + "engines": { 78 78 + "node": ">=14.21.3" 79 79 + } 80 80 + }, 81 81 + "node_modules/@biomejs/cli-linux-arm64": { 82 82 + "version": "2.3.5", 83 83 + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.3.5.tgz", 84 84 + "integrity": "sha512-u/pybjTBPGBHB66ku4pK1gj+Dxgx7/+Z0jAriZISPX1ocTO8aHh8x8e7Kb1rB4Ms0nA/SzjtNOVJ4exVavQBCw==", 85 85 + "cpu": [ 86 86 + "arm64" 87 87 + ], 88 88 + "dev": true, 89 89 + "license": "MIT OR Apache-2.0", 90 90 + "optional": true, 91 91 + "os": [ 92 92 + "linux" 93 93 + ], 94 94 + "engines": { 95 95 + "node": ">=14.21.3" 96 96 + } 97 97 + }, 98 98 + "node_modules/@biomejs/cli-linux-arm64-musl": { 99 99 + "version": "2.3.5", 100 100 + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.3.5.tgz", 101 101 + "integrity": "sha512-eGUG7+hcLgGnMNl1KHVZUYxahYAhC462jF/wQolqu4qso2MSk32Q+QrpN7eN4jAHAg7FUMIo897muIhK4hXhqg==", 102 102 + "cpu": [ 103 103 + "arm64" 104 104 + ], 105 105 + "dev": true, 106 106 + "license": "MIT OR Apache-2.0", 107 107 + "optional": true, 108 108 + "os": [ 109 109 + "linux" 110 110 + ], 111 111 + "engines": { 112 112 + "node": ">=14.21.3" 113 113 + } 114 114 + }, 115 115 + "node_modules/@biomejs/cli-linux-x64": { 116 116 + "version": "2.3.5", 117 117 + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.3.5.tgz", 118 118 + "integrity": "sha512-XrIVi9YAW6ye0CGQ+yax0gLfx+BFOtKaNX74n+xHWla6Cl6huUmcKNO7HPx7BiKnJUzrxXY1qYlm7xMvi08X4g==", 119 119 + "cpu": [ 120 120 + "x64" 121 121 + ], 122 122 + "dev": true, 123 123 + "license": "MIT OR Apache-2.0", 124 124 + "optional": true, 125 125 + "os": [ 126 126 + "linux" 127 127 + ], 128 128 + "engines": { 129 129 + "node": ">=14.21.3" 130 130 + } 131 131 + }, 132 132 + "node_modules/@biomejs/cli-linux-x64-musl": { 133 133 + "version": "2.3.5", 134 134 + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.3.5.tgz", 135 135 + "integrity": "sha512-awVuycTPpVTH/+WDVnEEYSf6nbCBHf/4wB3lquwT7puhNg8R4XvonWNZzUsfHZrCkjkLhFH/vCZK5jHatD9FEg==", 136 136 + "cpu": [ 137 137 + "x64" 138 138 + ], 139 139 + "dev": true, 140 140 + "license": "MIT OR Apache-2.0", 141 141 + "optional": true, 142 142 + "os": [ 143 143 + "linux" 144 144 + ], 145 145 + "engines": { 146 146 + "node": ">=14.21.3" 147 147 + } 148 148 + }, 149 149 + "node_modules/@biomejs/cli-win32-arm64": { 150 150 + "version": "2.3.5", 151 151 + "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.3.5.tgz", 152 152 + "integrity": "sha512-DlBiMlBZZ9eIq4H7RimDSGsYcOtfOIfZOaI5CqsWiSlbTfqbPVfWtCf92wNzx8GNMbu1s7/g3ZZESr6+GwM/SA==", 153 153 + "cpu": [ 154 154 + "arm64" 155 155 + ], 156 156 + "dev": true, 157 157 + "license": "MIT OR Apache-2.0", 158 158 + "optional": true, 159 159 + "os": [ 160 160 + "win32" 161 161 + ], 162 162 + "engines": { 163 163 + "node": ">=14.21.3" 164 164 + } 165 165 + }, 166 166 + "node_modules/@biomejs/cli-win32-x64": { 167 167 + "version": "2.3.5", 168 168 + "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.3.5.tgz", 169 169 + "integrity": "sha512-nUmR8gb6yvrKhtRgzwo/gDimPwnO5a4sCydf8ZS2kHIJhEmSmk+STsusr1LHTuM//wXppBawvSQi2xFXJCdgKQ==", 170 170 + "cpu": [ 171 171 + "x64" 172 172 + ], 173 173 + "dev": true, 174 174 + "license": "MIT OR Apache-2.0", 175 175 + "optional": true, 176 176 + "os": [ 177 177 + "win32" 178 178 + ], 179 179 + "engines": { 180 180 + "node": ">=14.21.3" 181 181 + } 182 182 + }, 183 183 + "node_modules/@types/node": { 184 184 + "version": "24.10.0", 185 185 + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.10.0.tgz", 186 186 + "integrity": "sha512-qzQZRBqkFsYyaSWXuEHc2WR9c0a0CXwiE5FWUvn7ZM+vdy1uZLfCunD38UzhuB7YN/J11ndbDBcTmOdxJo9Q7A==", 187 187 + "dev": true, 188 188 + "license": "MIT", 189 189 + "dependencies": { 190 190 + "undici-types": "~7.16.0" 191 191 + } 192 192 + }, 193 193 + "node_modules/typescript": { 194 194 + "version": "5.9.3", 195 195 + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", 196 196 + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", 197 197 + "dev": true, 198 198 + "license": "Apache-2.0", 199 199 + "bin": { 200 200 + "tsc": "bin/tsc", 201 201 + "tsserver": "bin/tsserver" 202 202 + }, 203 203 + "engines": { 204 204 + "node": ">=14.17" 205 205 + } 206 206 + }, 207 207 + "node_modules/undici-types": { 208 208 + "version": "7.16.0", 209 209 + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz", 210 210 + "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==", 211 211 + "dev": true, 212 212 + "license": "MIT" 213 213 + } 214 214 + } 215 215 + }

+28

package.json

··· 1 1 + { 2 2 + "name": "tagged-string", 3 3 + "version": "0.0.0", 4 4 + "description": "Lightweight, zero-dependency TypeScript library for extracting structured entity information from strings using tag-based syntax", 5 5 + "license": "MIT", 6 6 + "author": "tbeseda", 7 7 + "type": "module", 8 8 + "main": "./src/TaggedStringParser.ts", 9 9 + "types": "./src/types.ts", 10 10 + "exports": { 11 11 + ".": "./src/TaggedStringParser.ts", 12 12 + "./types": "./src/types.ts" 13 13 + }, 14 14 + "scripts": { 15 15 + "lint": "biome check --write", 16 16 + "test": "node --test src/**/*.test.ts", 17 17 + "posttest": "npm run lint", 18 18 + "examples": "node --experimental-strip-types src/examples.ts" 19 19 + }, 20 20 + "engines": { 21 21 + "node": ">=24.0.0" 22 22 + }, 23 23 + "devDependencies": { 24 24 + "@biomejs/biome": "2.3.5", 25 25 + "@types/node": "^24.10.0", 26 26 + "typescript": "^5.7.2" 27 27 + } 28 28 + }

+547

src/ParseResult.test.ts

··· 1 1 + import assert from 'node:assert' 2 2 + import { describe, test } from 'node:test' 3 3 + import { ParseResult } from './ParseResult.ts' 4 4 + import type { Entity } from './types.ts' 5 5 + 6 6 + describe('ParseResult', () => { 7 7 + describe('getEntitiesByType', () => { 8 8 + test('should return entities matching the specified type', () => { 9 9 + const entities: Entity[] = [ 10 10 + { 11 11 + type: 'operation', 12 12 + value: 'OP-123', 13 13 + parsedValue: 'OP-123', 14 14 + formattedValue: 'OP-123', 15 15 + inferredType: 'string', 16 16 + position: 0, 17 17 + endPosition: 18, 18 18 + }, 19 19 + { 20 20 + type: 'count', 21 21 + value: '5', 22 22 + parsedValue: 5, 23 23 + formattedValue: '5', 24 24 + inferredType: 'number', 25 25 + position: 20, 26 26 + endPosition: 28, 27 27 + }, 28 28 + { 29 29 + type: 'operation', 30 30 + value: 'OP-456', 31 31 + parsedValue: 'OP-456', 32 32 + formattedValue: 'OP-456', 33 33 + inferredType: 'string', 34 34 + position: 30, 35 35 + endPosition: 48, 36 36 + }, 37 37 + ] 38 38 + const result = new ParseResult( 39 39 + '[operation:OP-123] [count:5] [operation:OP-456]', 40 40 + entities, 41 41 + ) 42 42 + 43 43 + const operations = result.getEntitiesByType('operation') 44 44 + 45 45 + assert.strictEqual(operations.length, 2) 46 46 + assert.strictEqual(operations[0].value, 'OP-123') 47 47 + assert.strictEqual(operations[1].value, 'OP-456') 48 48 + }) 49 49 + 50 50 + test('should return empty array for non-matching type', () => { 51 51 + const entities: Entity[] = [ 52 52 + { 53 53 + type: 'operation', 54 54 + value: 'OP-123', 55 55 + parsedValue: 'OP-123', 56 56 + formattedValue: 'OP-123', 57 57 + inferredType: 'string', 58 58 + position: 0, 59 59 + endPosition: 18, 60 60 + }, 61 61 + ] 62 62 + const result = new ParseResult('[operation:OP-123]', entities) 63 63 + 64 64 + const stacks = result.getEntitiesByType('stack') 65 65 + 66 66 + assert.strictEqual(stacks.length, 0) 67 67 + assert.ok(Array.isArray(stacks)) 68 68 + }) 69 69 + 70 70 + test('should preserve entity order', () => { 71 71 + const entities: Entity[] = [ 72 72 + { 73 73 + type: 'item', 74 74 + value: 'first', 75 75 + parsedValue: 'first', 76 76 + formattedValue: 'first', 77 77 + inferredType: 'string', 78 78 + position: 0, 79 79 + endPosition: 12, 80 80 + }, 81 81 + { 82 82 + type: 'item', 83 83 + value: 'second', 84 84 + parsedValue: 'second', 85 85 + formattedValue: 'second', 86 86 + inferredType: 'string', 87 87 + position: 10, 88 88 + endPosition: 23, 89 89 + }, 90 90 + { 91 91 + type: 'item', 92 92 + value: 'third', 93 93 + parsedValue: 'third', 94 94 + formattedValue: 'third', 95 95 + inferredType: 'string', 96 96 + position: 20, 97 97 + endPosition: 32, 98 98 + }, 99 99 + ] 100 100 + const result = new ParseResult( 101 101 + '[item:first] [item:second] [item:third]', 102 102 + entities, 103 103 + ) 104 104 + 105 105 + const items = result.getEntitiesByType('item') 106 106 + 107 107 + assert.strictEqual(items[0].value, 'first') 108 108 + assert.strictEqual(items[1].value, 'second') 109 109 + assert.strictEqual(items[2].value, 'third') 110 110 + }) 111 111 + }) 112 112 + 113 113 + describe('getAllTypes', () => { 114 114 + test('should return all unique entity types', () => { 115 115 + const entities: Entity[] = [ 116 116 + { 117 117 + type: 'operation', 118 118 + value: 'OP-123', 119 119 + parsedValue: 'OP-123', 120 120 + formattedValue: 'OP-123', 121 121 + inferredType: 'string', 122 122 + position: 0, 123 123 + endPosition: 18, 124 124 + }, 125 125 + { 126 126 + type: 'count', 127 127 + value: '5', 128 128 + parsedValue: 5, 129 129 + formattedValue: '5', 130 130 + inferredType: 'number', 131 131 + position: 20, 132 132 + endPosition: 28, 133 133 + }, 134 134 + { 135 135 + type: 'stack', 136 136 + value: 'ST-456', 137 137 + parsedValue: 'ST-456', 138 138 + formattedValue: 'ST-456', 139 139 + inferredType: 'string', 140 140 + position: 30, 141 141 + endPosition: 43, 142 142 + }, 143 143 + { 144 144 + type: 'operation', 145 145 + value: 'OP-789', 146 146 + parsedValue: 'OP-789', 147 147 + formattedValue: 'OP-789', 148 148 + inferredType: 'string', 149 149 + position: 45, 150 150 + endPosition: 63, 151 151 + }, 152 152 + ] 153 153 + const result = new ParseResult( 154 154 + '[operation:OP-123] [count:5] [stack:ST-456] [operation:OP-789]', 155 155 + entities, 156 156 + ) 157 157 + 158 158 + const types = result.getAllTypes() 159 159 + 160 160 + assert.strictEqual(types.length, 3) 161 161 + assert.ok(types.includes('operation')) 162 162 + assert.ok(types.includes('count')) 163 163 + assert.ok(types.includes('stack')) 164 164 + }) 165 165 + 166 166 + test('should return empty array when no entities exist', () => { 167 167 + const result = new ParseResult('No entities here', []) 168 168 + 169 169 + const types = result.getAllTypes() 170 170 + 171 171 + assert.strictEqual(types.length, 0) 172 172 + assert.ok(Array.isArray(types)) 173 173 + }) 174 174 + }) 175 175 + 176 176 + describe('format', () => { 177 177 + test('should reconstruct message with formatted entity values', () => { 178 178 + const entities: Entity[] = [ 179 179 + { 180 180 + type: 'operation', 181 181 + value: 'OP-123', 182 182 + parsedValue: 'OP-123', 183 183 + formattedValue: 'OP-123', 184 184 + inferredType: 'string', 185 185 + position: 0, 186 186 + endPosition: 18, 187 187 + }, 188 188 + { 189 189 + type: 'count', 190 190 + value: '5', 191 191 + parsedValue: 5, 192 192 + formattedValue: '5', 193 193 + inferredType: 'number', 194 194 + position: 32, 195 195 + endPosition: 41, 196 196 + }, 197 197 + ] 198 198 + const result = new ParseResult( 199 199 + '[operation:OP-123] started with [count:5]', 200 200 + entities, 201 201 + ) 202 202 + 203 203 + const formatted = result.format() 204 204 + 205 205 + assert.strictEqual(formatted, 'OP-123 started with 5') 206 206 + }) 207 207 + 208 208 + test('should apply custom formatters to entity values', () => { 209 209 + const entities: Entity[] = [ 210 210 + { 211 211 + type: 'operation', 212 212 + value: 'OP-123', 213 213 + parsedValue: 'OP-123', 214 214 + formattedValue: '**OP-123**', 215 215 + inferredType: 'string', 216 216 + position: 0, 217 217 + endPosition: 18, 218 218 + }, 219 219 + { 220 220 + type: 'count', 221 221 + value: '5', 222 222 + parsedValue: 5, 223 223 + formattedValue: '[5 items]', 224 224 + inferredType: 'number', 225 225 + position: 32, 226 226 + endPosition: 41, 227 227 + }, 228 228 + ] 229 229 + const result = new ParseResult( 230 230 + '[operation:OP-123] started with [count:5]', 231 231 + entities, 232 232 + ) 233 233 + 234 234 + const formatted = result.format() 235 235 + 236 236 + assert.strictEqual(formatted, '**OP-123** started with [5 items]') 237 237 + }) 238 238 + 239 239 + test('should handle multiple entities with different formatters', () => { 240 240 + const entities: Entity[] = [ 241 241 + { 242 242 + type: 'name', 243 243 + value: 'alice', 244 244 + parsedValue: 'alice', 245 245 + formattedValue: 'ALICE', 246 246 + inferredType: 'string', 247 247 + position: 0, 248 248 + endPosition: 12, 249 249 + }, 250 250 + { 251 251 + type: 'count', 252 252 + value: '5', 253 253 + parsedValue: 5, 254 254 + formattedValue: '5 items', 255 255 + inferredType: 'number', 256 256 + position: 17, 257 257 + endPosition: 26, 258 258 + }, 259 259 + ] 260 260 + const result = new ParseResult( 261 261 + '[name:alice] has [count:5] total', 262 262 + entities, 263 263 + ) 264 264 + 265 265 + const formatted = result.format() 266 266 + 267 267 + assert.strictEqual(formatted, 'ALICE has 5 items total') 268 268 + }) 269 269 + 270 270 + test('should return original message when no entities exist', () => { 271 271 + const result = new ParseResult('No entities here', []) 272 272 + 273 273 + const formatted = result.format() 274 274 + 275 275 + assert.strictEqual(formatted, 'No entities here') 276 276 + }) 277 277 + 278 278 + test('should preserve text between and around entities', () => { 279 279 + const entities: Entity[] = [ 280 280 + { 281 281 + type: 'a', 282 282 + value: '1', 283 283 + parsedValue: 1, 284 284 + formattedValue: 'ONE', 285 285 + inferredType: 'number', 286 286 + position: 7, 287 287 + endPosition: 12, 288 288 + }, 289 289 + { 290 290 + type: 'b', 291 291 + value: '2', 292 292 + parsedValue: 2, 293 293 + formattedValue: 'TWO', 294 294 + inferredType: 'number', 295 295 + position: 20, 296 296 + endPosition: 25, 297 297 + }, 298 298 + ] 299 299 + const result = new ParseResult('Start: [a:1] middle [b:2] end', entities) 300 300 + 301 301 + const formatted = result.format() 302 302 + 303 303 + assert.strictEqual(formatted, 'Start: ONE middle TWO end') 304 304 + }) 305 305 + }) 306 306 + 307 307 + describe('format with custom delimiters', () => { 308 308 + test('should format message with custom single-character delimiters', () => { 309 309 + const entities: Entity[] = [ 310 310 + { 311 311 + type: 'operation', 312 312 + value: 'OP-123', 313 313 + parsedValue: 'OP-123', 314 314 + formattedValue: 'OP-123', 315 315 + inferredType: 'string', 316 316 + position: 0, 317 317 + endPosition: 18, 318 318 + }, 319 319 + { 320 320 + type: 'count', 321 321 + value: '5', 322 322 + parsedValue: 5, 323 323 + formattedValue: '5', 324 324 + inferredType: 'number', 325 325 + position: 32, 326 326 + endPosition: 41, 327 327 + }, 328 328 + ] 329 329 + const result = new ParseResult( 330 330 + '<operation:OP-123> started with <count:5>', 331 331 + entities, 332 332 + '>', 333 333 + ) 334 334 + 335 335 + const formatted = result.format() 336 336 + 337 337 + assert.strictEqual(formatted, 'OP-123 started with 5') 338 338 + }) 339 339 + 340 340 + test('should format message with custom multi-character delimiters', () => { 341 341 + const entities: Entity[] = [ 342 342 + { 343 343 + type: 'user', 344 344 + value: 'john', 345 345 + parsedValue: 'john', 346 346 + formattedValue: '@john', 347 347 + inferredType: 'string', 348 348 + position: 5, 349 349 + endPosition: 18, 350 350 + }, 351 351 + { 352 352 + type: 'count', 353 353 + value: '10', 354 354 + parsedValue: 10, 355 355 + formattedValue: '10', 356 356 + inferredType: 'number', 357 357 + position: 29, 358 358 + endPosition: 41, 359 359 + }, 360 360 + ] 361 361 + const result = new ParseResult( 362 362 + 'User {{user:john}} performed {{count:10}} actions', 363 363 + entities, 364 364 + '}}', 365 365 + ) 366 366 + 367 367 + const formatted = result.format() 368 368 + 369 369 + assert.strictEqual(formatted, 'User @john performed 10 actions') 370 370 + }) 371 371 + 372 372 + test('should format message with custom type separator', () => { 373 373 + const entities: Entity[] = [ 374 374 + { 375 375 + type: 'operation', 376 376 + value: 'OP-123', 377 377 + parsedValue: 'OP-123', 378 378 + formattedValue: 'OP-123', 379 379 + inferredType: 'string', 380 380 + position: 0, 381 381 + endPosition: 18, 382 382 + }, 383 383 + ] 384 384 + const result = new ParseResult('[operation=OP-123]', entities, ']') 385 385 + 386 386 + const formatted = result.format() 387 387 + 388 388 + assert.strictEqual(formatted, 'OP-123') 389 389 + }) 390 390 + 391 391 + test('should format message with all custom delimiters combined', () => { 392 392 + const entities: Entity[] = [ 393 393 + { 394 394 + type: 'operation', 395 395 + value: 'OP-123', 396 396 + parsedValue: 'OP-123', 397 397 + formattedValue: '**OP-123**', 398 398 + inferredType: 'string', 399 399 + position: 0, 400 400 + endPosition: 20, 401 401 + }, 402 402 + { 403 403 + type: 'count', 404 404 + value: '5', 405 405 + parsedValue: 5, 406 406 + formattedValue: '[5 items]', 407 407 + inferredType: 'number', 408 408 + position: 34, 409 409 + endPosition: 46, 410 410 + }, 411 411 + ] 412 412 + const result = new ParseResult( 413 413 + '<<operation|OP-123>> started with <<count|5>>', 414 414 + entities, 415 415 + '>>', 416 416 + ) 417 417 + 418 418 + const formatted = result.format() 419 419 + 420 420 + assert.strictEqual(formatted, '**OP-123** started with [5 items]') 421 421 + }) 422 422 + 423 423 + test('should maintain backward compatibility with default delimiters', () => { 424 424 + const entities: Entity[] = [ 425 425 + { 426 426 + type: 'operation', 427 427 + value: 'OP-123', 428 428 + parsedValue: 'OP-123', 429 429 + formattedValue: 'OP-123', 430 430 + inferredType: 'string', 431 431 + position: 0, 432 432 + endPosition: 18, 433 433 + }, 434 434 + ] 435 435 + const result = new ParseResult('[operation:OP-123]', entities) 436 436 + 437 437 + const formatted = result.format() 438 438 + 439 439 + assert.strictEqual(formatted, 'OP-123') 440 440 + }) 441 441 + 442 442 + test('should correctly apply formatters with custom delimiters', () => { 443 443 + const entities: Entity[] = [ 444 444 + { 445 445 + type: 'user', 446 446 + value: 'alice', 447 447 + parsedValue: 'alice', 448 448 + formattedValue: 'ALICE', 449 449 + inferredType: 'string', 450 450 + position: 0, 451 451 + endPosition: 12, 452 452 + }, 453 453 + { 454 454 + type: 'count', 455 455 + value: '42', 456 456 + parsedValue: 42, 457 457 + formattedValue: '42 items', 458 458 + inferredType: 'number', 459 459 + position: 17, 460 460 + endPosition: 27, 461 461 + }, 462 462 + ] 463 463 + const result = new ParseResult( 464 464 + '{user:alice} has {count:42}', 465 465 + entities, 466 466 + '}', 467 467 + ) 468 468 + 469 469 + const formatted = result.format() 470 470 + 471 471 + assert.strictEqual(formatted, 'ALICE has 42 items') 472 472 + }) 473 473 + 474 474 + test('should format multiple entities using custom delimiters', () => { 475 475 + const entities: Entity[] = [ 476 476 + { 477 477 + type: 'a', 478 478 + value: '1', 479 479 + parsedValue: 1, 480 480 + formattedValue: 'ONE', 481 481 + inferredType: 'number', 482 482 + position: 7, 483 483 + endPosition: 12, 484 484 + }, 485 485 + { 486 486 + type: 'b', 487 487 + value: '2', 488 488 + parsedValue: 2, 489 489 + formattedValue: 'TWO', 490 490 + inferredType: 'number', 491 491 + position: 20, 492 492 + endPosition: 25, 493 493 + }, 494 494 + { 495 495 + type: 'c', 496 496 + value: '3', 497 497 + parsedValue: 3, 498 498 + formattedValue: 'THREE', 499 499 + inferredType: 'number', 500 500 + position: 30, 501 501 + endPosition: 35, 502 502 + }, 503 503 + ] 504 504 + const result = new ParseResult( 505 505 + 'Start: <a:1> middle <b:2> and <c:3> end', 506 506 + entities, 507 507 + '>', 508 508 + ) 509 509 + 510 510 + const formatted = result.format() 511 511 + 512 512 + assert.strictEqual(formatted, 'Start: ONE middle TWO and THREE end') 513 513 + }) 514 514 + 515 515 + test('should handle real-world example from TODO.md with curly brace delimiters', () => { 516 516 + const entities: Entity[] = [ 517 517 + { 518 518 + type: 'user', 519 519 + value: 'john', 520 520 + parsedValue: 'john', 521 521 + formattedValue: '@john', 522 522 + inferredType: 'string', 523 523 + position: 5, 524 524 + endPosition: 18, 525 525 + }, 526 526 + { 527 527 + type: 'count', 528 528 + value: '10', 529 529 + parsedValue: 10, 530 530 + formattedValue: '10', 531 531 + inferredType: 'number', 532 532 + position: 29, 533 533 + endPosition: 41, 534 534 + }, 535 535 + ] 536 536 + const result = new ParseResult( 537 537 + 'User {{user=john}} performed {{count=10}} actions', 538 538 + entities, 539 539 + '}}', 540 540 + ) 541 541 + 542 542 + const formatted = result.format() 543 543 + 544 544 + assert.strictEqual(formatted, 'User @john performed 10 actions') 545 545 + }) 546 546 + }) 547 547 + })

+93

src/ParseResult.ts

··· 1 1 + import type { Entity, ParseResult as IParseResult } from './types.ts' 2 2 + 3 3 + /** 4 4 + * Implementation of ParseResult interface 5 5 + * Holds the original message and extracted entities with utility methods 6 6 + */ 7 7 + export class ParseResult implements IParseResult { 8 8 + public readonly originalMessage: string 9 9 + public readonly entities: Entity[] 10 10 + private readonly closeDelimiter?: string 11 11 + 12 12 + constructor( 13 13 + originalMessage: string, 14 14 + entities: Entity[], 15 15 + closeDelimiter?: string, 16 16 + ) { 17 17 + this.originalMessage = originalMessage 18 18 + this.entities = entities 19 19 + this.closeDelimiter = closeDelimiter 20 20 + } 21 21 + 22 22 + /** 23 23 + * Get all entities of a specific type 24 24 + * @param type - The entity type to filter by 25 25 + * @returns Array of entities matching the type, in original order 26 26 + */ 27 27 + getEntitiesByType(type: string): Entity[] { 28 28 + return this.entities.filter((entity) => entity.type === type) 29 29 + } 30 30 + 31 31 + /** 32 32 + * Get all unique entity types found in the message 33 33 + * @returns Array of unique type strings 34 34 + */ 35 35 + getAllTypes(): string[] { 36 36 + const types = new Set<string>() 37 37 + for (const entity of this.entities) { 38 38 + types.add(entity.type) 39 39 + } 40 40 + return Array.from(types) 41 41 + } 42 42 + 43 43 + /** 44 44 + * Reconstruct the message with formatted entity values 45 45 + * Replaces tags with their formattedValue from entities 46 46 + * @returns Formatted string with all entities replaced 47 47 + */ 48 48 + format(): string { 49 49 + if (this.entities.length === 0) { 50 50 + return this.originalMessage 51 51 + } 52 52 + 53 53 + // Sort entities by position to process them in order 54 54 + const sortedEntities = [...this.entities].sort( 55 55 + (a, b) => a.position - b.position, 56 56 + ) 57 57 + 58 58 + let result = '' 59 59 + let lastIndex = 0 60 60 + 61 61 + for (const entity of sortedEntities) { 62 62 + // Add text before this entity 63 63 + result += this.originalMessage.substring(lastIndex, entity.position) 64 64 + 65 65 + // Add the formatted value instead of the original tag 66 66 + result += entity.formattedValue 67 67 + 68 68 + // Use stored endPosition if available, otherwise fall back to searching 69 69 + let tagEnd: number 70 70 + if (entity.endPosition !== undefined) { 71 71 + tagEnd = entity.endPosition 72 72 + } else { 73 73 + // Fallback: search for closing delimiter 74 74 + const delimiter = this.closeDelimiter ?? ']' 75 75 + const closingDelimiterIndex = this.originalMessage.indexOf( 76 76 + delimiter, 77 77 + entity.position, 78 78 + ) 79 79 + tagEnd = 80 80 + closingDelimiterIndex !== -1 81 81 + ? closingDelimiterIndex + delimiter.length 82 82 + : entity.position 83 83 + } 84 84 + 85 85 + lastIndex = tagEnd 86 86 + } 87 87 + 88 88 + // Add remaining text after the last entity 89 89 + result += this.originalMessage.substring(lastIndex) 90 90 + 91 91 + return result 92 92 + } 93 93 + }

+593

src/TaggedStringParser.test.ts

··· 1 1 + import assert from 'node:assert' 2 2 + import { describe, test } from 'node:test' 3 3 + import { TaggedStringParser } from './TaggedStringParser.ts' 4 4 + import type { EntitySchema } from './types.ts' 5 5 + 6 6 + describe('TaggedStringParser', () => { 7 7 + describe('basic parsing', () => { 8 8 + test('should extract single entity', () => { 9 9 + const parser = new TaggedStringParser() 10 10 + const result = parser.parse('[operation:OP-123]') 11 11 + 12 12 + assert.strictEqual(result.entities.length, 1) 13 13 + assert.strictEqual(result.entities[0].type, 'operation') 14 14 + assert.strictEqual(result.entities[0].value, 'OP-123') 15 15 + assert.strictEqual(result.entities[0].position, 0) 16 16 + }) 17 17 + 18 18 + test('should extract multiple entities in one message', () => { 19 19 + const parser = new TaggedStringParser() 20 20 + const result = parser.parse( 21 21 + '[operation:OP-123] started with [changes:5] to [stack:ST-456]', 22 22 + ) 23 23 + 24 24 + assert.strictEqual(result.entities.length, 3) 25 25 + assert.strictEqual(result.entities[0].type, 'operation') 26 26 + assert.strictEqual(result.entities[0].value, 'OP-123') 27 27 + assert.strictEqual(result.entities[1].type, 'changes') 28 28 + assert.strictEqual(result.entities[1].value, '5') 29 29 + assert.strictEqual(result.entities[2].type, 'stack') 30 30 + assert.strictEqual(result.entities[2].value, 'ST-456') 31 31 + }) 32 32 + 33 33 + test('should handle messages without entities', () => { 34 34 + const parser = new TaggedStringParser() 35 35 + const result = parser.parse('This is a plain log message') 36 36 + 37 37 + assert.strictEqual(result.entities.length, 0) 38 38 + assert.strictEqual(result.originalMessage, 'This is a plain log message') 39 39 + }) 40 40 + 41 41 + test('should handle empty string', () => { 42 42 + const parser = new TaggedStringParser() 43 43 + const result = parser.parse('') 44 44 + 45 45 + assert.strictEqual(result.entities.length, 0) 46 46 + assert.strictEqual(result.originalMessage, '') 47 47 + }) 48 48 + }) 49 49 + 50 50 + describe('custom delimiter configuration', () => { 51 51 + test('should use custom delimiters', () => { 52 52 + const parser = new TaggedStringParser({ 53 53 + openDelimiter: '{', 54 54 + closeDelimiter: '}', 55 55 + }) 56 56 + const result = parser.parse('{operation:OP-123} started') 57 57 + 58 58 + assert.strictEqual(result.entities.length, 1) 59 59 + assert.strictEqual(result.entities[0].type, 'operation') 60 60 + assert.strictEqual(result.entities[0].value, 'OP-123') 61 61 + }) 62 62 + 63 63 + test('should use custom type separator', () => { 64 64 + const parser = new TaggedStringParser({ 65 65 + typeSeparator: '=', 66 66 + }) 67 67 + const result = parser.parse('[operation=OP-123]') 68 68 + 69 69 + assert.strictEqual(result.entities.length, 1) 70 70 + assert.strictEqual(result.entities[0].type, 'operation') 71 71 + assert.strictEqual(result.entities[0].value, 'OP-123') 72 72 + }) 73 73 + 74 74 + test('should use multiple custom configurations together', () => { 75 75 + const parser = new TaggedStringParser({ 76 76 + openDelimiter: '<', 77 77 + closeDelimiter: '>', 78 78 + typeSeparator: '|', 79 79 + }) 80 80 + const result = parser.parse('<operation|OP-123> started') 81 81 + 82 82 + assert.strictEqual(result.entities.length, 1) 83 83 + assert.strictEqual(result.entities[0].type, 'operation') 84 84 + assert.strictEqual(result.entities[0].value, 'OP-123') 85 85 + }) 86 86 + }) 87 87 + 88 88 + describe('configuration validation', () => { 89 89 + test('should throw error for empty open delimiter', () => { 90 90 + assert.throws( 91 91 + () => new TaggedStringParser({ openDelimiter: '' }), 92 92 + /Open delimiter cannot be empty/, 93 93 + ) 94 94 + }) 95 95 + 96 96 + test('should throw error for empty close delimiter', () => { 97 97 + assert.throws( 98 98 + () => new TaggedStringParser({ closeDelimiter: '' }), 99 99 + /Close delimiter cannot be empty/, 100 100 + ) 101 101 + }) 102 102 + 103 103 + test('should throw error when delimiters are the same', () => { 104 104 + assert.throws( 105 105 + () => 106 106 + new TaggedStringParser({ openDelimiter: '|', closeDelimiter: '|' }), 107 107 + /Open and close delimiters cannot be the same/, 108 108 + ) 109 109 + }) 110 110 + }) 111 111 + 112 112 + describe('malformed tag handling', () => { 113 113 + test('should skip unclosed tag at end of string', () => { 114 114 + const parser = new TaggedStringParser() 115 115 + const result = parser.parse('[operation:OP-123] started [incomplete') 116 116 + 117 117 + assert.strictEqual(result.entities.length, 1) 118 118 + assert.strictEqual(result.entities[0].type, 'operation') 119 119 + assert.strictEqual(result.entities[0].value, 'OP-123') 120 120 + }) 121 121 + 122 122 + test('should handle tag without type separator', () => { 123 123 + const parser = new TaggedStringParser() 124 124 + const result = parser.parse('[justvalue]') 125 125 + 126 126 + assert.strictEqual(result.entities.length, 1) 127 127 + assert.strictEqual(result.entities[0].type, '') 128 128 + assert.strictEqual(result.entities[0].value, 'justvalue') 129 129 + }) 130 130 + 131 131 + test('should skip empty tags', () => { 132 132 + const parser = new TaggedStringParser() 133 133 + const result = parser.parse('[operation:OP-123] [] [stack:ST-456]') 134 134 + 135 135 + assert.strictEqual(result.entities.length, 2) 136 136 + assert.strictEqual(result.entities[0].type, 'operation') 137 137 + assert.strictEqual(result.entities[1].type, 'stack') 138 138 + }) 139 139 + 140 140 + test('should skip tags with only whitespace', () => { 141 141 + const parser = new TaggedStringParser() 142 142 + const result = parser.parse('[operation:OP-123] [ ] [stack:ST-456]') 143 143 + 144 144 + assert.strictEqual(result.entities.length, 2) 145 145 + assert.strictEqual(result.entities[0].type, 'operation') 146 146 + assert.strictEqual(result.entities[1].type, 'stack') 147 147 + }) 148 148 + }) 149 149 + 150 150 + describe('entity position tracking', () => { 151 151 + test('should track position of single entity', () => { 152 152 + const parser = new TaggedStringParser() 153 153 + const result = parser.parse('[operation:OP-123]') 154 154 + 155 155 + assert.strictEqual(result.entities[0].position, 0) 156 156 + }) 157 157 + 158 158 + test('should track positions of multiple entities', () => { 159 159 + const parser = new TaggedStringParser() 160 160 + const result = parser.parse('[operation:OP-123] started with [changes:5]') 161 161 + 162 162 + assert.strictEqual(result.entities[0].position, 0) 163 163 + assert.strictEqual(result.entities[1].position, 32) 164 164 + }) 165 165 + 166 166 + test('should track position with text before entity', () => { 167 167 + const parser = new TaggedStringParser() 168 168 + const result = parser.parse('Starting [operation:OP-123] now') 169 169 + 170 170 + assert.strictEqual(result.entities[0].position, 9) 171 171 + }) 172 172 + }) 173 173 + 174 174 + describe('schema-based type parsing', () => { 175 175 + test('should parse known entity using schema type', () => { 176 176 + const schema: EntitySchema = { 177 177 + count: 'number', 178 178 + enabled: 'boolean', 179 179 + name: 'string', 180 180 + } 181 181 + const parser = new TaggedStringParser({ schema }) 182 182 + const result = parser.parse('[count:42] [enabled:true] [name:test]') 183 183 + 184 184 + assert.strictEqual(result.entities[0].parsedValue, 42) 185 185 + assert.strictEqual(result.entities[0].inferredType, 'number') 186 186 + assert.strictEqual(result.entities[1].parsedValue, true) 187 187 + assert.strictEqual(result.entities[1].inferredType, 'boolean') 188 188 + assert.strictEqual(result.entities[2].parsedValue, 'test') 189 189 + assert.strictEqual(result.entities[2].inferredType, 'string') 190 190 + }) 191 191 + 192 192 + test('should parse number from schema even if value looks like string', () => { 193 193 + const schema: EntitySchema = { 194 194 + id: 'number', 195 195 + } 196 196 + const parser = new TaggedStringParser({ schema }) 197 197 + const result = parser.parse('[id:123]') 198 198 + 199 199 + assert.strictEqual(result.entities[0].parsedValue, 123) 200 200 + assert.strictEqual(typeof result.entities[0].parsedValue, 'number') 201 201 + }) 202 202 + 203 203 + test('should parse boolean from schema case-insensitively', () => { 204 204 + const schema: EntitySchema = { 205 205 + flag: 'boolean', 206 206 + } 207 207 + const parser = new TaggedStringParser({ schema }) 208 208 + const result = parser.parse('[flag:TRUE] [flag:False]') 209 209 + 210 210 + assert.strictEqual(result.entities[0].parsedValue, true) 211 211 + assert.strictEqual(result.entities[1].parsedValue, false) 212 212 + }) 213 213 + }) 214 214 + 215 215 + describe('automatic type inference', () => { 216 216 + test('should infer number type for numeric values', () => { 217 217 + const parser = new TaggedStringParser() 218 218 + const result = parser.parse('[count:42] [price:19.99] [temp:-5]') 219 219 + 220 220 + assert.strictEqual(result.entities[0].parsedValue, 42) 221 221 + assert.strictEqual(result.entities[0].inferredType, 'number') 222 222 + assert.strictEqual(result.entities[1].parsedValue, 19.99) 223 223 + assert.strictEqual(result.entities[1].inferredType, 'number') 224 224 + assert.strictEqual(result.entities[2].parsedValue, -5) 225 225 + assert.strictEqual(result.entities[2].inferredType, 'number') 226 226 + }) 227 227 + 228 228 + test('should infer boolean type for true/false values', () => { 229 229 + const parser = new TaggedStringParser() 230 230 + const result = parser.parse( 231 231 + '[enabled:true] [disabled:false] [active:TRUE]', 232 232 + ) 233 233 + 234 234 + assert.strictEqual(result.entities[0].parsedValue, true) 235 235 + assert.strictEqual(result.entities[0].inferredType, 'boolean') 236 236 + assert.strictEqual(result.entities[1].parsedValue, false) 237 237 + assert.strictEqual(result.entities[1].inferredType, 'boolean') 238 238 + assert.strictEqual(result.entities[2].parsedValue, true) 239 239 + assert.strictEqual(result.entities[2].inferredType, 'boolean') 240 240 + }) 241 241 + 242 242 + test('should infer string type for other values', () => { 243 243 + const parser = new TaggedStringParser() 244 244 + const result = parser.parse( 245 245 + '[name:test] [id:abc123] [message:hello world]', 246 246 + ) 247 247 + 248 248 + assert.strictEqual(result.entities[0].parsedValue, 'test') 249 249 + assert.strictEqual(result.entities[0].inferredType, 'string') 250 250 + assert.strictEqual(result.entities[1].parsedValue, 'abc123') 251 251 + assert.strictEqual(result.entities[1].inferredType, 'string') 252 252 + assert.strictEqual(result.entities[2].parsedValue, 'hello world') 253 253 + assert.strictEqual(result.entities[2].inferredType, 'string') 254 254 + }) 255 255 + }) 256 256 + 257 257 + describe('mixed known and unknown entities', () => { 258 258 + test('should handle both schema-defined and inferred entities', () => { 259 259 + const schema: EntitySchema = { 260 260 + operation: 'string', 261 261 + changes: 'number', 262 262 + } 263 263 + const parser = new TaggedStringParser({ schema }) 264 264 + const result = parser.parse( 265 265 + '[operation:OP-123] with [changes:5] and [unknown:42]', 266 266 + ) 267 267 + 268 268 + // Schema-defined entities 269 269 + assert.strictEqual(result.entities[0].type, 'operation') 270 270 + assert.strictEqual(result.entities[0].parsedValue, 'OP-123') 271 271 + assert.strictEqual(result.entities[0].inferredType, 'string') 272 272 + 273 273 + assert.strictEqual(result.entities[1].type, 'changes') 274 274 + assert.strictEqual(result.entities[1].parsedValue, 5) 275 275 + assert.strictEqual(result.entities[1].inferredType, 'number') 276 276 + 277 277 + // Unknown entity with inference 278 278 + assert.strictEqual(result.entities[2].type, 'unknown') 279 279 + assert.strictEqual(result.entities[2].parsedValue, 42) 280 280 + assert.strictEqual(result.entities[2].inferredType, 'number') 281 281 + }) 282 282 + }) 283 283 + 284 284 + describe('formatter functions', () => { 285 285 + test('should apply formatter to entity values', () => { 286 286 + const schema: EntitySchema = { 287 287 + operation: { 288 288 + type: 'string', 289 289 + format: (val) => `**${val}**`, 290 290 + }, 291 291 + count: { 292 292 + type: 'number', 293 293 + format: (val) => `[${val} items]`, 294 294 + }, 295 295 + } 296 296 + const parser = new TaggedStringParser({ schema }) 297 297 + const result = parser.parse('[operation:OP-123] has [count:5]') 298 298 + 299 299 + assert.strictEqual(result.entities[0].formattedValue, '**OP-123**') 300 300 + assert.strictEqual(result.entities[1].formattedValue, '[5 items]') 301 301 + }) 302 302 + 303 303 + test('should apply formatter with uppercase transformation', () => { 304 304 + const schema: EntitySchema = { 305 305 + name: { 306 306 + type: 'string', 307 307 + format: (val) => val.toUpperCase(), 308 308 + }, 309 309 + } 310 310 + const parser = new TaggedStringParser({ schema }) 311 311 + const result = parser.parse('[name:alice]') 312 312 + 313 313 + assert.strictEqual(result.entities[0].formattedValue, 'ALICE') 314 314 + }) 315 315 + }) 316 316 + 317 317 + describe('entities without formatters', () => { 318 318 + test('should default to string conversion when no formatter provided', () => { 319 319 + const schema: EntitySchema = { 320 320 + count: 'number', 321 321 + enabled: 'boolean', 322 322 + } 323 323 + const parser = new TaggedStringParser({ schema }) 324 324 + const result = parser.parse('[count:42] [enabled:true]') 325 325 + 326 326 + assert.strictEqual(result.entities[0].formattedValue, '42') 327 327 + assert.strictEqual(result.entities[1].formattedValue, 'true') 328 328 + }) 329 329 + 330 330 + test('should convert unknown entities to string', () => { 331 331 + const parser = new TaggedStringParser() 332 332 + const result = parser.parse('[count:42] [enabled:true] [name:test]') 333 333 + 334 334 + assert.strictEqual(result.entities[0].formattedValue, '42') 335 335 + assert.strictEqual(result.entities[1].formattedValue, 'true') 336 336 + assert.strictEqual(result.entities[2].formattedValue, 'test') 337 337 + }) 338 338 + }) 339 339 + 340 340 + describe('shorthand vs full EntityDefinition', () => { 341 341 + test('should support shorthand schema syntax', () => { 342 342 + const schema: EntitySchema = { 343 343 + count: 'number', 344 344 + name: 'string', 345 345 + } 346 346 + const parser = new TaggedStringParser({ schema }) 347 347 + const result = parser.parse('[count:42] [name:test]') 348 348 + 349 349 + assert.strictEqual(result.entities[0].parsedValue, 42) 350 350 + assert.strictEqual(result.entities[0].inferredType, 'number') 351 351 + assert.strictEqual(result.entities[1].parsedValue, 'test') 352 352 + assert.strictEqual(result.entities[1].inferredType, 'string') 353 353 + }) 354 354 + 355 355 + test('should support full EntityDefinition with formatter', () => { 356 356 + const schema: EntitySchema = { 357 357 + count: { 358 358 + type: 'number', 359 359 + format: (val) => `Count: ${val}`, 360 360 + }, 361 361 + } 362 362 + const parser = new TaggedStringParser({ schema }) 363 363 + const result = parser.parse('[count:42]') 364 364 + 365 365 + assert.strictEqual(result.entities[0].parsedValue, 42) 366 366 + assert.strictEqual(result.entities[0].formattedValue, 'Count: 42') 367 367 + }) 368 368 + 369 369 + test('should mix shorthand and full definitions in same schema', () => { 370 370 + const schema: EntitySchema = { 371 371 + count: 'number', 372 372 + name: { 373 373 + type: 'string', 374 374 + format: (val) => val.toUpperCase(), 375 375 + }, 376 376 + } 377 377 + const parser = new TaggedStringParser({ schema }) 378 378 + const result = parser.parse('[count:42] [name:alice]') 379 379 + 380 380 + assert.strictEqual(result.entities[0].parsedValue, 42) 381 381 + assert.strictEqual(result.entities[0].formattedValue, '42') 382 382 + assert.strictEqual(result.entities[1].parsedValue, 'alice') 383 383 + assert.strictEqual(result.entities[1].formattedValue, 'ALICE') 384 384 + }) 385 385 + }) 386 386 + 387 387 + describe('endPosition calculation', () => { 388 388 + test('should calculate endPosition with single-character delimiters (default)', () => { 389 389 + const parser = new TaggedStringParser() 390 390 + const result = parser.parse('[operation:OP-123]') 391 391 + 392 392 + assert.strictEqual(result.entities[0].position, 0) 393 393 + assert.strictEqual(result.entities[0].endPosition, 18) 394 394 + }) 395 395 + 396 396 + test('should calculate endPosition with multi-character delimiters', () => { 397 397 + const parser = new TaggedStringParser({ 398 398 + openDelimiter: '{{', 399 399 + closeDelimiter: '}}', 400 400 + }) 401 401 + const result = parser.parse('{{operation:OP-123}}') 402 402 + 403 403 + assert.strictEqual(result.entities[0].position, 0) 404 404 + assert.strictEqual(result.entities[0].endPosition, 20) 405 405 + }) 406 406 + 407 407 + test('should calculate endPosition for multiple entities in one message', () => { 408 408 + const parser = new TaggedStringParser() 409 409 + const result = parser.parse( 410 410 + '[operation:OP-123] started with [changes:5] to [stack:ST-456]', 411 411 + ) 412 412 + 413 413 + assert.strictEqual(result.entities.length, 3) 414 414 + 415 415 + // First entity 416 416 + assert.strictEqual(result.entities[0].position, 0) 417 417 + assert.strictEqual(result.entities[0].endPosition, 18) 418 418 + 419 419 + // Second entity 420 420 + assert.strictEqual(result.entities[1].position, 32) 421 421 + assert.strictEqual(result.entities[1].endPosition, 43) 422 422 + 423 423 + // Third entity 424 424 + assert.strictEqual(result.entities[2].position, 47) 425 425 + assert.strictEqual(result.entities[2].endPosition, 61) 426 426 + }) 427 427 + 428 428 + test('should calculate endPosition for entity at start of message', () => { 429 429 + const parser = new TaggedStringParser() 430 430 + const result = parser.parse('[operation:OP-123] started') 431 431 + 432 432 + assert.strictEqual(result.entities[0].position, 0) 433 433 + assert.strictEqual(result.entities[0].endPosition, 18) 434 434 + }) 435 435 + 436 436 + test('should calculate endPosition for entity in middle of message', () => { 437 437 + const parser = new TaggedStringParser() 438 438 + const result = parser.parse('Starting [operation:OP-123] now') 439 439 + 440 440 + assert.strictEqual(result.entities[0].position, 9) 441 441 + assert.strictEqual(result.entities[0].endPosition, 27) 442 442 + }) 443 443 + 444 444 + test('should calculate endPosition for entity at end of message', () => { 445 445 + const parser = new TaggedStringParser() 446 446 + const result = parser.parse('Completed [operation:OP-123]') 447 447 + 448 448 + assert.strictEqual(result.entities[0].position, 10) 449 449 + assert.strictEqual(result.entities[0].endPosition, 28) 450 450 + }) 451 451 + 452 452 + test('should calculate endPosition correctly with custom single-character delimiters', () => { 453 453 + const parser = new TaggedStringParser({ 454 454 + openDelimiter: '<', 455 455 + closeDelimiter: '>', 456 456 + }) 457 457 + const result = parser.parse('<operation:OP-123>') 458 458 + 459 459 + assert.strictEqual(result.entities[0].position, 0) 460 460 + assert.strictEqual(result.entities[0].endPosition, 18) 461 461 + }) 462 462 + 463 463 + test('should calculate endPosition correctly with longer multi-character delimiters', () => { 464 464 + const parser = new TaggedStringParser({ 465 465 + openDelimiter: '<<<', 466 466 + closeDelimiter: '>>>', 467 467 + }) 468 468 + const result = parser.parse('<<<operation:OP-123>>>') 469 469 + 470 470 + assert.strictEqual(result.entities[0].position, 0) 471 471 + assert.strictEqual(result.entities[0].endPosition, 22) 472 472 + }) 473 473 + 474 474 + test('should calculate endPosition for multiple entities with custom delimiters', () => { 475 475 + const parser = new TaggedStringParser({ 476 476 + openDelimiter: '{{', 477 477 + closeDelimiter: '}}', 478 478 + }) 479 479 + const result = parser.parse( 480 480 + 'User {{user:john}} performed {{count:10}} actions', 481 481 + ) 482 482 + 483 483 + assert.strictEqual(result.entities.length, 2) 484 484 + 485 485 + // First entity 486 486 + assert.strictEqual(result.entities[0].position, 5) 487 487 + assert.strictEqual(result.entities[0].endPosition, 18) 488 488 + 489 489 + // Second entity 490 490 + assert.strictEqual(result.entities[1].position, 29) 491 491 + assert.strictEqual(result.entities[1].endPosition, 41) 492 492 + }) 493 493 + }) 494 494 + 495 495 + describe('real-world IaC log examples', () => { 496 496 + test('should parse operation lifecycle logs', () => { 497 497 + const schema: EntitySchema = { 498 498 + operation: 'string', 499 499 + changes: 'number', 500 500 + stack: 'string', 501 501 + } 502 502 + const parser = new TaggedStringParser({ schema }) 503 503 + 504 504 + const result1 = parser.parse( 505 505 + '[operation:OP-123] started with [changes:5] to [stack:ST-456]', 506 506 + ) 507 507 + assert.strictEqual(result1.entities.length, 3) 508 508 + assert.strictEqual(result1.entities[0].parsedValue, 'OP-123') 509 509 + assert.strictEqual(result1.entities[1].parsedValue, 5) 510 510 + assert.strictEqual(result1.entities[2].parsedValue, 'ST-456') 511 511 + 512 512 + const result2 = parser.parse( 513 513 + '[operation:OP-123] completed [changes:5] to [stack:ST-456]', 514 514 + ) 515 515 + assert.strictEqual(result2.entities.length, 3) 516 516 + }) 517 517 + 518 518 + test('should parse planning logs', () => { 519 519 + const schema: EntitySchema = { 520 520 + blueprint: 'string', 521 521 + stack: 'string', 522 522 + create: 'number', 523 523 + update: 'number', 524 524 + destroy: 'number', 525 525 + } 526 526 + const parser = new TaggedStringParser({ schema }) 527 527 + 528 528 + const result = parser.parse( 529 529 + '[blueprint:BP-123] plan complete with [create:2] [update:3] [destroy:1] for [stack:ST-456]', 530 530 + ) 531 531 + 532 532 + assert.strictEqual(result.entities.length, 5) 533 533 + assert.strictEqual(result.entities[0].parsedValue, 'BP-123') 534 534 + assert.strictEqual(result.entities[1].parsedValue, 2) 535 535 + assert.strictEqual(result.entities[2].parsedValue, 3) 536 536 + assert.strictEqual(result.entities[3].parsedValue, 1) 537 537 + assert.strictEqual(result.entities[4].parsedValue, 'ST-456') 538 538 + }) 539 539 + 540 540 + test('should parse resource command logs', () => { 541 541 + const schema: EntitySchema = { 542 542 + action: 'string', 543 543 + resource: 'string', 544 544 + resourceName: 'string', 545 545 + type: 'string', 546 546 + externalId: 'string', 547 547 + } 548 548 + const parser = new TaggedStringParser({ schema }) 549 549 + 550 550 + const result1 = parser.parse( 551 551 + '[action:create] executing for [resource:RS-123] [resourceName:"my-function"] [type:function]', 552 552 + ) 553 553 + assert.strictEqual(result1.entities.length, 4) 554 554 + assert.strictEqual(result1.entities[0].parsedValue, 'create') 555 555 + assert.strictEqual(result1.entities[2].parsedValue, '"my-function"') 556 556 + 557 557 + const result2 = parser.parse( 558 558 + '[action:create] completed for [resource:RS-123] [externalId:EXT-789]', 559 559 + ) 560 560 + assert.strictEqual(result2.entities.length, 3) 561 561 + }) 562 562 + 563 563 + test('should preserve quoted values in entity values', () => { 564 564 + const parser = new TaggedStringParser() 565 565 + const result = parser.parse( 566 566 + '[resourceName:"my-function"] [error:"Error message"]', 567 567 + ) 568 568 + 569 569 + assert.strictEqual(result.entities[0].value, '"my-function"') 570 570 + assert.strictEqual(result.entities[1].value, '"Error message"') 571 571 + }) 572 572 + 573 573 + test('should parse resource type-specific logs', () => { 574 574 + const schema: EntitySchema = { 575 575 + resourceType: 'string', 576 576 + resourceName: 'string', 577 577 + } 578 578 + const parser = new TaggedStringParser({ schema }) 579 579 + 580 580 + const result1 = parser.parse( 581 581 + '[resourceType:function] creating [resourceName:"my-function"]', 582 582 + ) 583 583 + assert.strictEqual(result1.entities[0].parsedValue, 'function') 584 584 + assert.strictEqual(result1.entities[1].parsedValue, '"my-function"') 585 585 + 586 586 + const result2 = parser.parse( 587 587 + '[resourceType:database] updating [resourceName:"user-db"]', 588 588 + ) 589 589 + assert.strictEqual(result2.entities[0].parsedValue, 'database') 590 590 + assert.strictEqual(result2.entities[1].parsedValue, '"user-db"') 591 591 + }) 592 592 + }) 593 593 + })

+232

src/TaggedStringParser.ts

··· 1 1 + import { ParseResult } from './ParseResult.ts' 2 2 + import type { 3 3 + Entity, 4 4 + EntitySchema, 5 5 + ParserConfig, 6 6 + PrimitiveType, 7 7 + } from './types.ts' 8 8 + 9 9 + /** 10 10 + * TaggedStringParser extracts tagged entities from strings 11 11 + * Supports configurable delimiters, schema-based type parsing, and automatic type inference 12 12 + */ 13 13 + export class TaggedStringParser { 14 14 + private readonly openDelimiter: string 15 15 + private readonly closeDelimiter: string 16 16 + private readonly typeSeparator: string 17 17 + private readonly schema?: EntitySchema 18 18 + 19 19 + /** 20 20 + * Create a new TaggedStringParser with optional configuration 21 21 + * @param config - Parser configuration options 22 22 + * @throws Error if configuration is invalid 23 23 + */ 24 24 + constructor(config?: ParserConfig) { 25 25 + // Set defaults 26 26 + this.openDelimiter = config?.openDelimiter ?? '[' 27 27 + this.closeDelimiter = config?.closeDelimiter ?? ']' 28 28 + this.typeSeparator = config?.typeSeparator ?? ':' 29 29 + this.schema = config?.schema 30 30 + 31 31 + // Validate configuration 32 32 + this.validateConfig() 33 33 + } 34 34 + 35 35 + /** 36 36 + * Validate parser configuration 37 37 + * @throws Error if configuration is invalid 38 38 + */ 39 39 + private validateConfig(): void { 40 40 + if (this.openDelimiter === '') { 41 41 + throw new Error('Open delimiter cannot be empty') 42 42 + } 43 43 + if (this.closeDelimiter === '') { 44 44 + throw new Error('Close delimiter cannot be empty') 45 45 + } 46 46 + if (this.openDelimiter === this.closeDelimiter) { 47 47 + throw new Error('Open and close delimiters cannot be the same') 48 48 + } 49 49 + } 50 50 + 51 51 + /** 52 52 + * Parse a string and extract all tagged entities 53 53 + * @param message - The string to parse 54 54 + * @returns ParseResult containing original message and extracted entities 55 55 + */ 56 56 + parse(message: string): ParseResult { 57 57 + if (message === '') { 58 58 + return new ParseResult(message, []) 59 59 + } 60 60 + 61 61 + // Escape special regex characters in delimiters 62 62 + const escapeRegex = (str: string) => 63 63 + str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') 64 64 + const openEscaped = escapeRegex(this.openDelimiter) 65 65 + const closeEscaped = escapeRegex(this.closeDelimiter) 66 66 + 67 67 + // Build regex to match tags: openDelimiter + content + closeDelimiter 68 68 + const tagRegex = new RegExp( 69 69 + `${openEscaped}([^${closeEscaped}]+?)${closeEscaped}`, 70 70 + 'g', 71 71 + ) 72 72 + 73 73 + const entities: Entity[] = [] 74 74 + 75 75 + for (const match of message.matchAll(tagRegex)) { 76 76 + const tagContent = match[1].trim() 77 77 + 78 78 + if (tagContent !== '' && match.index !== undefined) { 79 79 + const entity = this.processTag( 80 80 + tagContent, 81 81 + match.index, 82 82 + match.index + match[0].length, 83 83 + ) 84 84 + if (entity) { 85 85 + entities.push(entity) 86 86 + } 87 87 + } 88 88 + } 89 89 + 90 90 + return new ParseResult(message, entities, this.closeDelimiter) 91 91 + } 92 92 + 93 93 + /** 94 94 + * Process a tag's content and create an Entity 95 95 + * @param tagContent - The content between delimiters 96 96 + * @param position - The position of the tag in the original message 97 97 + * @param endPosition - The position after the closing delimiter 98 98 + * @returns Entity or null if tag is malformed 99 99 + */ 100 100 + private processTag( 101 101 + tagContent: string, 102 102 + position: number, 103 103 + endPosition: number, 104 104 + ): Entity | null { 105 105 + // Find the type separator 106 106 + const separatorIndex = tagContent.indexOf(this.typeSeparator) 107 107 + 108 108 + let type: string 109 109 + let value: string 110 110 + 111 111 + if (separatorIndex === -1) { 112 112 + // No separator - treat entire content as value with empty type 113 113 + type = '' 114 114 + value = tagContent 115 115 + } else { 116 116 + // Split by separator 117 117 + type = tagContent.substring(0, separatorIndex) 118 118 + value = tagContent.substring(separatorIndex + 1) 119 119 + } 120 120 + 121 121 + // Parse the value and get typed result 122 122 + const { parsedValue, inferredType } = this.parseValue(type, value) 123 123 + 124 124 + // Apply formatter to get formatted value 125 125 + const formattedValue = this.applyFormatter(type, parsedValue) 126 126 + 127 127 + return { 128 128 + type, 129 129 + value, 130 130 + parsedValue, 131 131 + formattedValue, 132 132 + inferredType, 133 133 + position, 134 134 + endPosition, 135 135 + } 136 136 + } 137 137 + 138 138 + /** 139 139 + * Infer the primitive type from a raw string value 140 140 + * @param value - The raw string value 141 141 + * @returns The inferred primitive type 142 142 + */ 143 143 + private inferType(value: string): PrimitiveType { 144 144 + // Check for number (including decimals and negatives) 145 145 + if (/^-?\d+(\.\d+)?$/.test(value)) { 146 146 + return 'number' 147 147 + } 148 148 + 149 149 + // Check for boolean (case-insensitive) 150 150 + const lowerValue = value.toLowerCase() 151 151 + if (lowerValue === 'true' || lowerValue === 'false') { 152 152 + return 'boolean' 153 153 + } 154 154 + 155 155 + // Default to string 156 156 + return 'string' 157 157 + } 158 158 + 159 159 + /** 160 160 + * Parse a value using schema (if available) or type inference 161 161 + * @param type - The entity type 162 162 + * @param rawValue - The raw string value 163 163 + * @returns Object with parsedValue and inferredType 164 164 + */ 165 165 + private parseValue( 166 166 + type: string, 167 167 + rawValue: string, 168 168 + ): { 169 169 + parsedValue: string | number | boolean 170 170 + inferredType: PrimitiveType 171 171 + } { 172 172 + let targetType: PrimitiveType 173 173 + 174 174 + // Check if type is in schema 175 175 + if (this.schema && type in this.schema) { 176 176 + const schemaEntry = this.schema[type] 177 177 + // Handle both shorthand (just type) and full definition 178 178 + targetType = 179 179 + typeof schemaEntry === 'string' ? schemaEntry : schemaEntry.type 180 180 + } else { 181 181 + // Use inference for unknown types 182 182 + targetType = this.inferType(rawValue) 183 183 + } 184 184 + 185 185 + // Parse based on target type 186 186 + let parsedValue: string | number | boolean 187 187 + 188 188 + switch (targetType) { 189 189 + case 'number': 190 190 + parsedValue = parseFloat(rawValue) 191 191 + break 192 192 + case 'boolean': 193 193 + parsedValue = rawValue.toLowerCase() === 'true' 194 194 + break 195 195 + case 'string': 196 196 + parsedValue = rawValue 197 197 + break 198 198 + default: 199 199 + parsedValue = rawValue 200 200 + break 201 201 + } 202 202 + 203 203 + return { 204 204 + parsedValue, 205 205 + inferredType: targetType, 206 206 + } 207 207 + } 208 208 + 209 209 + /** 210 210 + * Apply formatter function to a parsed value 211 211 + * @param type - The entity type 212 212 + * @param parsedValue - The parsed value 213 213 + * @returns Formatted string 214 214 + */ 215 215 + private applyFormatter( 216 216 + type: string, 217 217 + parsedValue: string | number | boolean, 218 218 + ): string { 219 219 + // Check if schema has a formatter for this type 220 220 + if (this.schema && type in this.schema) { 221 221 + const schemaEntry = this.schema[type] 222 222 + 223 223 + // Only full EntityDefinition can have a formatter 224 224 + if (typeof schemaEntry !== 'string' && schemaEntry.format) { 225 225 + return schemaEntry.format(parsedValue) 226 226 + } 227 227 + } 228 228 + 229 229 + // No formatter - convert to string 230 230 + return String(parsedValue) 231 231 + } 232 232 + }

+305

src/examples.ts

··· 1 1 + /** 2 2 + * Example usage of TaggedStringParser 3 3 + * Demonstrates basic usage, schema definition, formatters, and type inference 4 4 + * 5 5 + * Run with: node src/examples.ts 6 6 + */ 7 7 + 8 8 + import { TaggedStringParser } from './TaggedStringParser.ts' 9 9 + import type { EntitySchema } from './types.ts' 10 10 + 11 11 + // ============================================================================ 12 12 + // Example 1: Basic Usage with Schema and Simple String Formatters 13 13 + // ============================================================================ 14 14 + 15 15 + console.log('=== Example 1: Basic Usage with String Formatters ===\n') 16 16 + 17 17 + const basicSchema: EntitySchema = { 18 18 + operation: { type: 'string', format: (v) => v.toUpperCase() }, 19 19 + stack: { type: 'string', format: (v) => v.trim() }, 20 20 + changes: { type: 'number', format: (n) => `${n} changes` }, 21 21 + status: 'string', // Shorthand without formatter 22 22 + } 23 23 + 24 24 + const basicParser = new TaggedStringParser({ schema: basicSchema }) 25 25 + const result1 = basicParser.parse( 26 26 + '[operation:deploy] started with [changes:5] to [stack: prod-stack ]', 27 27 + ) 28 28 + 29 29 + console.log('Original message:', result1.originalMessage) 30 30 + console.log('Formatted message:', result1.format()) 31 31 + console.log('\nParsed entities:') 32 32 + result1.entities.forEach((entity) => { 33 33 + console.log(` - Type: ${entity.type}`) 34 34 + console.log(` Raw value: "${entity.value}"`) 35 35 + console.log( 36 36 + ` Parsed value: ${entity.parsedValue} (${entity.inferredType})`, 37 37 + ) 38 38 + console.log(` Formatted value: "${entity.formattedValue}"`) 39 39 + console.log(` Position: ${entity.position}`) 40 40 + }) 41 41 + 42 42 + // ============================================================================ 43 43 + // Example 2: Automatic Type Inference for Unknown Entities 44 44 + // ============================================================================ 45 45 + 46 46 + console.log('\n\n=== Example 2: Automatic Type Inference ===\n') 47 47 + 48 48 + const inferenceParser = new TaggedStringParser() // No schema 49 49 + const result2 = inferenceParser.parse( 50 50 + '[count:42] items processed, [enabled:true] flag set, [name:test-service]', 51 51 + ) 52 52 + 53 53 + console.log('Message:', result2.originalMessage) 54 54 + console.log('\nInferred types:') 55 55 + result2.entities.forEach((entity) => { 56 56 + console.log( 57 57 + ` - [${entity.type}:${entity.value}] → ${entity.inferredType} (${typeof entity.parsedValue})`, 58 58 + ) 59 59 + console.log(` Parsed value: ${JSON.stringify(entity.parsedValue)}`) 60 60 + }) 61 61 + 62 62 + // ============================================================================ 63 63 + // Example 3: Entity Filtering by Type 64 64 + // ============================================================================ 65 65 + 66 66 + console.log('\n\n=== Example 3: Entity Filtering ===\n') 67 67 + 68 68 + const filterSchema: EntitySchema = { 69 69 + resource: 'string', 70 70 + action: 'string', 71 71 + count: 'number', 72 72 + } 73 73 + 74 74 + const filterParser = new TaggedStringParser({ schema: filterSchema }) 75 75 + const result3 = filterParser.parse( 76 76 + '[action:create] [resource:function] with [count:3] instances, [action:update] [resource:database]', 77 77 + ) 78 78 + 79 79 + console.log('All entity types:', result3.getAllTypes()) 80 80 + console.log( 81 81 + '\nActions:', 82 82 + result3.getEntitiesByType('action').map((e) => e.parsedValue), 83 83 + ) 84 84 + console.log( 85 85 + 'Resources:', 86 86 + result3.getEntitiesByType('resource').map((e) => e.parsedValue), 87 87 + ) 88 88 + console.log( 89 89 + 'Counts:', 90 90 + result3.getEntitiesByType('count').map((e) => e.parsedValue), 91 91 + ) 92 92 + console.log('Non-existent type:', result3.getEntitiesByType('missing')) 93 93 + 94 94 + // ============================================================================ 95 95 + // Example 4: IaC Logging Examples (from design document) 96 96 + // ============================================================================ 97 97 + 98 98 + console.log('\n\n=== Example 4: IaC Logging Examples ===\n') 99 99 + 100 100 + const iacSchema: EntitySchema = { 101 101 + operation: { type: 'string', format: (v) => `OP:${v}` }, 102 102 + stack: { type: 'string', format: (v) => `Stack(${v})` }, 103 103 + changes: { type: 'number', format: (n) => `${n} change(s)` }, 104 104 + blueprint: { type: 'string', format: (v) => `BP:${v}` }, 105 105 + create: 'number', 106 106 + update: 'number', 107 107 + destroy: 'number', 108 108 + action: 'string', 109 109 + resource: 'string', 110 110 + resourceName: 'string', 111 111 + type: 'string', 112 112 + externalId: 'string', 113 113 + reason: 'string', 114 114 + error: 'string', 115 115 + } 116 116 + 117 117 + const iacParser = new TaggedStringParser({ schema: iacSchema }) 118 118 + 119 119 + // Operation lifecycle 120 120 + console.log('Operation Lifecycle:') 121 121 + const op1 = iacParser.parse( 122 122 + '[operation:OP-123] started with [changes:5] to [stack:ST-456]', 123 123 + ) 124 124 + console.log(' ', op1.format()) 125 125 + 126 126 + const op2 = iacParser.parse( 127 127 + '[operation:OP-123] completed [changes:5] to [stack:ST-456]', 128 128 + ) 129 129 + console.log(' ', op2.format()) 130 130 + 131 131 + const op3 = iacParser.parse('[operation:OP-123] failed: [reason:Timeout error]') 132 132 + console.log(' ', op3.format()) 133 133 + 134 134 + // Planning 135 135 + console.log('\nPlanning:') 136 136 + const plan1 = iacParser.parse('[blueprint:BP-123] planning for [stack:ST-456]') 137 137 + console.log(' ', plan1.format()) 138 138 + 139 139 + const plan2 = iacParser.parse( 140 140 + '[blueprint:BP-123] plan complete with [create:2] [update:3] [destroy:1] for [stack:ST-456]', 141 141 + ) 142 142 + console.log(' ', plan2.format()) 143 143 + console.log(' Plan summary:', { 144 144 + create: plan2.getEntitiesByType('create')[0]?.parsedValue, 145 145 + update: plan2.getEntitiesByType('update')[0]?.parsedValue, 146 146 + destroy: plan2.getEntitiesByType('destroy')[0]?.parsedValue, 147 147 + }) 148 148 + 149 149 + // Resource commands 150 150 + console.log('\nResource Commands:') 151 151 + const res1 = iacParser.parse( 152 152 + '[action:create] executing for [resource:RS-123] [resourceName:my-function] [type:function]', 153 153 + ) 154 154 + console.log(' ', res1.format()) 155 155 + 156 156 + const res2 = iacParser.parse( 157 157 + '[action:create] completed for [resource:RS-123] [externalId:EXT-789]', 158 158 + ) 159 159 + console.log(' ', res2.format()) 160 160 + 161 161 + const res3 = iacParser.parse( 162 162 + '[action:create] failed for [resource:RS-123]: [error:Connection timeout]', 163 163 + ) 164 164 + console.log(' ', res3.format()) 165 165 + 166 166 + // ============================================================================ 167 167 + // Example 5: Custom Configuration (Delimiters with Formatting) 168 168 + // ============================================================================ 169 169 + 170 170 + console.log('\n\n=== Example 5: Custom Delimiters with Formatting ===\n') 171 171 + 172 172 + // This example demonstrates the fix for custom delimiter formatting 173 173 + // Previously, format() was hardcoded to use ']' and wouldn't work with custom delimiters 174 174 + // Now it correctly uses the configured delimiters to reconstruct messages 175 175 + 176 176 + const customParser = new TaggedStringParser({ 177 177 + openDelimiter: '{{', 178 178 + closeDelimiter: '}}', 179 179 + typeSeparator: '=', 180 180 + schema: { 181 181 + user: { type: 'string', format: (v) => `@${v}` }, 182 182 + count: { type: 'number', format: (v) => String(v) }, 183 183 + }, 184 184 + }) 185 185 + 186 186 + const result5 = customParser.parse( 187 187 + 'User {{user=john}} performed {{count=10}} actions', 188 188 + ) 189 189 + console.log('Original message:', result5.originalMessage) 190 190 + console.log('Formatted message:', result5.format()) 191 191 + console.log(' ✓ Custom delimiters {{}} work correctly with format()') 192 192 + console.log(' ✓ Formatters applied: user → @john, count → 10') 193 193 + 194 194 + console.log('\nParsed entities:') 195 195 + result5.entities.forEach((entity) => { 196 196 + console.log( 197 197 + ` - {{${entity.type}=${entity.value}}} at position ${entity.position}-${entity.endPosition}`, 198 198 + ) 199 199 + console.log(` Formatted as: "${entity.formattedValue}"`) 200 200 + }) 201 201 + 202 202 + // Additional custom delimiter examples 203 203 + console.log('\nOther custom delimiter configurations:') 204 204 + 205 205 + const angleParser = new TaggedStringParser({ 206 206 + openDelimiter: '<<', 207 207 + closeDelimiter: '>>', 208 208 + typeSeparator: ':', 209 209 + schema: { 210 210 + status: { type: 'string', format: (v) => v.toUpperCase() }, 211 211 + }, 212 212 + }) 213 213 + const angleResult = angleParser.parse('Operation <<status:success>> completed') 214 214 + console.log(' Angle brackets:', angleResult.format()) 215 215 + 216 216 + const parenParser = new TaggedStringParser({ 217 217 + openDelimiter: '(', 218 218 + closeDelimiter: ')', 219 219 + typeSeparator: ':', 220 220 + schema: { 221 221 + code: { type: 'number', format: (n) => `#${n}` }, 222 222 + }, 223 223 + }) 224 224 + const parenResult = parenParser.parse('Error (code:404) occurred') 225 225 + console.log(' Parentheses:', parenResult.format()) 226 226 + 227 227 + // ============================================================================ 228 228 + // Example 6: Mixed Known and Unknown Entities 229 229 + // ============================================================================ 230 230 + 231 231 + console.log('\n\n=== Example 6: Mixed Known and Unknown Entities ===\n') 232 232 + 233 233 + const mixedSchema: EntitySchema = { 234 234 + operation: { type: 'string', format: (v) => `[OP: ${v}]` }, 235 235 + // Other entity types will be inferred 236 236 + } 237 237 + 238 238 + const mixedParser = new TaggedStringParser({ schema: mixedSchema }) 239 239 + const result6 = mixedParser.parse( 240 240 + '[operation:deploy] with [timeout:30] seconds and [retry:true] flag', 241 241 + ) 242 242 + 243 243 + console.log('Formatted:', result6.format()) 244 244 + console.log('\nEntity details:') 245 245 + result6.entities.forEach((entity) => { 246 246 + const source = mixedSchema[entity.type] ? 'schema' : 'inferred' 247 247 + console.log( 248 248 + ` - ${entity.type}: ${entity.parsedValue} (${entity.inferredType}, ${source})`, 249 249 + ) 250 250 + }) 251 251 + 252 252 + // ============================================================================ 253 253 + // Example 7: Accessing Entity Properties 254 254 + // ============================================================================ 255 255 + 256 256 + console.log('\n\n=== Example 7: Accessing Entity Properties ===\n') 257 257 + 258 258 + const propsSchema: EntitySchema = { 259 259 + price: { type: 'number', format: (n) => `$${n.toFixed(2)}` }, 260 260 + available: { type: 'boolean', format: (b) => (b ? '✓' : '✗') }, 261 261 + product: 'string', 262 262 + } 263 263 + 264 264 + const propsParser = new TaggedStringParser({ schema: propsSchema }) 265 265 + const result7 = propsParser.parse( 266 266 + '[product:Widget] is [available:true] at [price:29.99]', 267 267 + ) 268 268 + 269 269 + console.log('Original message:', result7.originalMessage) 270 270 + console.log('Formatted message:', result7.format()) 271 271 + console.log('\nDetailed entity properties:') 272 272 + result7.entities.forEach((entity) => { 273 273 + console.log(`\n Entity: ${entity.type}`) 274 274 + console.log(` value (raw string): "${entity.value}"`) 275 275 + console.log( 276 276 + ` parsedValue (typed): ${JSON.stringify(entity.parsedValue)} (${typeof entity.parsedValue})`, 277 277 + ) 278 278 + console.log(` formattedValue (display): "${entity.formattedValue}"`) 279 279 + console.log(` inferredType: ${entity.inferredType}`) 280 280 + console.log(` position: ${entity.position}`) 281 281 + }) 282 282 + 283 283 + // ============================================================================ 284 284 + // Example 8: Handling Quoted Values 285 285 + // ============================================================================ 286 286 + 287 287 + console.log('\n\n=== Example 8: Handling Quoted Values ===\n') 288 288 + 289 289 + const quotedParser = new TaggedStringParser({ 290 290 + schema: { 291 291 + resourceName: 'string', 292 292 + error: 'string', 293 293 + }, 294 294 + }) 295 295 + 296 296 + const result8 = quotedParser.parse( 297 297 + '[resourceName:"my-function"] failed with [error:"Connection timeout"]', 298 298 + ) 299 299 + console.log('Original:', result8.originalMessage) 300 300 + console.log('\nEntity values (quotes preserved):') 301 301 + result8.entities.forEach((entity) => { 302 302 + console.log(` ${entity.type}: ${entity.value}`) 303 303 + }) 304 304 + 305 305 + console.log('\n=== Examples Complete ===\n')

+66

src/types.ts

··· 1 1 + /** 2 2 + * Primitive types supported by the parser 3 3 + */ 4 4 + export type PrimitiveType = 'string' | 'number' | 'boolean' 5 5 + 6 6 + /** 7 7 + * Entity definition with optional formatter function 8 8 + */ 9 9 + export interface EntityDefinition { 10 10 + type: PrimitiveType 11 11 + format?: (value: unknown) => string 12 12 + } 13 13 + 14 14 + /** 15 15 + * Schema mapping entity type names to their definitions 16 16 + * Can use shorthand (just the type) or full definition with formatter 17 17 + */ 18 18 + export type EntitySchema = Record<string, PrimitiveType | EntityDefinition> 19 19 + 20 20 + /** 21 21 + * Parsed entity extracted from a string 22 22 + */ 23 23 + export interface Entity { 24 24 + type: string 25 25 + value: string 26 26 + parsedValue: string | number | boolean 27 27 + formattedValue: string 28 28 + inferredType: PrimitiveType 29 29 + /** The starting position of the tag in the original message */ 30 30 + position: number 31 31 + /** The ending position of the tag in the original message (after the closing delimiter) */ 32 32 + endPosition: number 33 33 + } 34 34 + 35 35 + /** 36 36 + * Configuration options for the parser 37 37 + */ 38 38 + export interface ParserConfig { 39 39 + openDelimiter?: string 40 40 + closeDelimiter?: string 41 41 + typeSeparator?: string 42 42 + schema?: EntitySchema 43 43 + } 44 44 + 45 45 + /** 46 46 + * Result of parsing a string 47 47 + */ 48 48 + export interface ParseResult { 49 49 + originalMessage: string 50 50 + entities: Entity[] 51 51 + 52 52 + /** 53 53 + * Get all entities of a specific type 54 54 + */ 55 55 + getEntitiesByType(type: string): Entity[] 56 56 + 57 57 + /** 58 58 + * Get all unique entity types found in the message 59 59 + */ 60 60 + getAllTypes(): string[] 61 61 + 62 62 + /** 63 63 + * Reconstruct the message with formatted entity values 64 64 + */ 65 65 + format(): string 66 66 + }

+17

tsconfig.json

··· 1 1 + { 2 2 + "compilerOptions": { 3 3 + "target": "ES2022", 4 4 + "module": "ESNext", 5 5 + "moduleResolution": "node", 6 6 + "lib": ["ES2022"], 7 7 + "strict": true, 8 8 + "esModuleInterop": true, 9 9 + "skipLibCheck": true, 10 10 + "allowImportingTsExtensions": true, 11 11 + "forceConsistentCasingInFileNames": true, 12 12 + "resolveJsonModule": true, 13 13 + "noEmit": true 14 14 + }, 15 15 + "include": ["src/**/*"], 16 16 + "exclude": ["node_modules"] 17 17 + }