feat: add TypeScript type definitions

Author: getCurrentThread

package.json

@@ -1,9 +1,10 @@
 {
   "name": "safe-template-parser",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "A safe template string parser for JavaScript",
   "main": "safe-template-parser.js",
   "module": "safe-template-parser.js",
+  "types": "safe-template-parser.d.ts",
   "type": "module",
   "scripts": {
     "test": "echo \"No tests available\" && exit 0",

safe-template-parser.d.ts

@@ -0,0 +1,183 @@
+/**
+ * TypeScript type definitions for safe-template-parser
+ * A safe template string parser for JavaScript
+ */
+
+/**
+ * Token types used by the Lexer
+ */
+export const TokenType: {
+  readonly NUMBER: symbol;
+  readonly IDENTIFIER: symbol;
+  readonly OPERATOR: symbol;
+  readonly LEFT_PAREN: symbol;
+  readonly RIGHT_PAREN: symbol;
+  readonly LEFT_BRACKET: symbol;
+  readonly RIGHT_BRACKET: symbol;
+  readonly LEFT_BRACE: symbol;
+  readonly RIGHT_BRACE: symbol;
+  readonly COLON: symbol;
+  readonly COMMA: symbol;
+  readonly DOT: symbol;
+  readonly STRING: symbol;
+  readonly BOOLEAN: symbol;
+  readonly NULL: symbol;
+  readonly EOF: symbol;
+};
+
+/**
+ * AST node types used by the Parser
+ */
+export const ASTNodeType: {
+  readonly NUMBER: symbol;
+  readonly VARIABLE: symbol;
+  readonly BINARY_OP: symbol;
+  readonly UNARY_OP: symbol;
+  readonly FUNCTION_CALL: symbol;
+  readonly ARRAY_ACCESS: symbol;
+  readonly PROPERTY_ACCESS: symbol;
+  readonly TERNARY_OP: symbol;
+  readonly ARRAY_LITERAL: symbol;
+  readonly OBJECT_LITERAL: symbol;
+  readonly NULL: symbol;
+};
+
+/**
+ * Represents a single token produced by the Lexer
+ */
+export class Token {
+  type: symbol;
+  value: string | number | boolean | null;
+  constructor(type: symbol, value: string | number | boolean | null);
+}
+
+/**
+ * AST Node interface representing parsed expression tree nodes
+ */
+export interface ASTNode {
+  type: symbol;
+  value?: string | number | boolean | null;
+  left?: ASTNode;
+  right?: ASTNode;
+  operator?: string;
+  name?: string;
+  args?: ASTNode[];
+  object?: ASTNode;
+  property?: string | ASTNode;
+  condition?: ASTNode;
+  trueExpr?: ASTNode;
+  falseExpr?: ASTNode;
+  elements?: ASTNode[];
+  properties?: Array<{ key: string; value: ASTNode }>;
+}
+
+/**
+ * Lexer class that tokenizes input strings into tokens
+ */
+export class Lexer {
+  /**
+   * Creates a new Lexer instance
+   * @param input - The input string to tokenize
+   */
+  constructor(input: string);
+
+  /**
+   * Returns the next token from the input
+   */
+  nextToken(): Token;
+}
+
+/**
+ * Parser class that converts tokens into an Abstract Syntax Tree (AST)
+ */
+export class Parser {
+  /**
+   * Creates a new Parser instance
+   * @param lexer - The Lexer instance to read tokens from
+   */
+  constructor(lexer: Lexer);
+
+  /**
+   * Parses the token stream and returns the root AST node
+   */
+  parse(): ASTNode;
+}
+
+/**
+ * Type for allowed functions that can be used in templates
+ */
+export type AllowedFunctions = Record<string, (...args: unknown[]) => unknown>;
+
+/**
+ * Type for template data object
+ */
+export type TemplateData = Record<string, unknown>;
+
+/**
+ * Interpreter class that evaluates an AST with given data
+ */
+export class Interpreter {
+  /**
+   * Creates a new Interpreter instance
+   * @param tree - The AST to interpret
+   * @param data - The data object containing variable values
+   * @param allowedFunctions - Optional map of allowed functions
+   */
+  constructor(
+    tree: ASTNode,
+    data: TemplateData,
+    allowedFunctions?: AllowedFunctions
+  );
+
+  /**
+   * Interprets the AST and returns the result
+   */
+  interpret(): unknown;
+}
+
+/**
+ * Parses a template string and replaces expressions with evaluated values
+ *
+ * @param templateString - The template string containing {{expression}} placeholders
+ * @param data - The data object containing variable values
+ * @param allowedFunctions - Optional map of user-defined functions
+ * @returns The template string with all expressions evaluated and replaced
+ *
+ * @example
+ * ```typescript
+ * import { parseTemplateString } from 'safe-template-parser';
+ *
+ * const template = "Hello, {{name}}! You have {{count}} messages.";
+ * const data = { name: "Alice", count: 5 };
+ * const result = parseTemplateString(template, data);
+ * // Result: "Hello, Alice! You have 5 messages."
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With expressions
+ * const template = "Total: {{price * quantity}}";
+ * const data = { price: 100, quantity: 3 };
+ * const result = parseTemplateString(template, data);
+ * // Result: "Total: 300"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom functions
+ * const template = "Formatted: {{formatCurrency(amount)}}";
+ * const data = { amount: 1234.56 };
+ * const functions = {
+ *   formatCurrency: (n: number) => `$${n.toFixed(2)}`
+ * };
+ * const result = parseTemplateString(template, data, functions);
+ * // Result: "Formatted: $1234.56"
+ * ```
+ */
+export function parseTemplateString(
+  templateString: string,
+  data: TemplateData,
+  allowedFunctions?: AllowedFunctions
+): string;
+
+export default parseTemplateString;