simplex-lang 0.2.2 → 1.0.0

package/src/constants.ts

@@ -0,0 +1,30 @@
+// Topic reference token used in pipe expressions
+export const TOPIC_TOKEN = '%'
+
+// Generated variable names used in bootstrap code and visitors
+export const GEN = {
+  bool: 'bool',
+  bop: 'bop',
+  lop: 'lop',
+  uop: 'uop',
+  call: 'call',
+  getIdentifierValue: 'getIdentifierValue',
+  prop: 'prop',
+  pipe: 'pipe',
+  globals: 'globals',
+  get: 'get',
+  scope: 'scope',
+  _get: '_get',
+  _scope: '_scope',
+  _varNames: '_varNames',
+  _varValues: '_varValues',
+  ensObj: 'ensObj',
+  ensArr: 'ensArr',
+  str: 'str',
+  nna: 'nna',
+} as const
+
+// Semantic indices into the scope array [names, values, parent]
+export const SCOPE_NAMES = 0
+export const SCOPE_VALUES = 1
+export const SCOPE_PARENT = 2

package/src/error-mapping.ts

@@ -0,0 +1,112 @@
+import { ExpressionError } from './errors.js'
+import type { Location } from './simplex-tree.js'
+import type { SourceLocation } from './visitors.js'
+
+export type { SourceLocation }
+
+// --- ErrorMapper Interface ---
+
+export interface ErrorMapper {
+  /**
+   * Map a runtime error from generated code back to source expression location.
+   * Returns ExpressionError with source location, or null if unable to map.
+   *
+   * @param err — the caught runtime error
+   * @param expression — original SimplEx expression string
+   * @param offsets — source location mapping from code generation
+   * @param codeOffset — length of bootstrap code prepended before the expression
+   */
+  mapError(
+    err: unknown,
+    expression: string,
+    offsets: SourceLocation[],
+    codeOffset: number
+  ): ExpressionError | null
+
+  /**
+   * Test if this mapper is compatible with the current JS engine.
+   * Called once during registration.
+   */
+  probe(): boolean
+}
+
+// --- Helper ---
+
+/** Map a code column offset back to an AST Location via the offsets array. */
+export function getExpressionErrorLocation(
+  colOffset: number,
+  locations: SourceLocation[]
+): Location | null {
+  var curCol = 0
+  for (const loc of locations) {
+    curCol += loc.len
+    if (curCol >= colOffset) return loc.location
+  }
+  return null
+}
+
+// --- V8 ErrorMapper ---
+
+var V8_STACK_REGEX = /<anonymous>:(?<row>\d+):(?<col>\d+)/g
+
+export var v8ErrorMapper: ErrorMapper = {
+  probe() {
+    try {
+      new Function('throw new Error("__simplex_probe__")')()
+    } catch (err) {
+      return /<anonymous>:\d+:\d+/.test((err as Error).stack ?? '')
+    }
+    return false
+  },
+
+  mapError(err, expression, offsets, codeOffset) {
+    if (!(err instanceof Error)) return null
+
+    var evalRow = err.stack
+      ?.split('\n')
+      .map(r => r.trim())
+      .find(r => r.startsWith('at eval '))
+    if (!evalRow) return null
+
+    V8_STACK_REGEX.lastIndex = 0
+    var match = V8_STACK_REGEX.exec(evalRow)
+    var rowStr = match?.groups?.['row']
+    var colStr = match?.groups?.['col']
+    if (!rowStr || !colStr) return null
+
+    var row = Number.parseInt(rowStr)
+    if (row !== 3) return null
+
+    var col = Number.parseInt(colStr)
+    var adjustedCol = col - codeOffset
+    if (adjustedCol < 0) return null
+
+    var location = getExpressionErrorLocation(adjustedCol, offsets)
+    return new ExpressionError(err.message, expression, location, {
+      cause: err
+    })
+  }
+}
+
+// --- Registration ---
+
+var activeErrorMapper: ErrorMapper | null = null
+
+/**
+ * Register an ErrorMapper. If the mapper passes its probe(), it becomes
+ * the active mapper. Skips if the mapper is already active.
+ */
+export function registerErrorMapper(mapper: ErrorMapper): void {
+  if (activeErrorMapper === mapper) return
+  if (mapper.probe()) {
+    activeErrorMapper = mapper
+  }
+}
+
+/** Get the currently active ErrorMapper (auto-detected or last registered). */
+export function getActiveErrorMapper(): ErrorMapper | null {
+  return activeErrorMapper
+}
+
+// Auto-register V8 mapper at module load
+registerErrorMapper(v8ErrorMapper)

package/src/errors.ts

@@ -1,7 +1,8 @@
 import { Location } from './simplex-tree.js'
 import { typeOf } from './tools/index.js'
 
-export class ExpressionError extends Error {
+/** Base error with source expression and location info. */
+export class SimplexError extends Error {
   constructor(
     message: string,
     public expression: string,
@@ -13,18 +14,13 @@ export class ExpressionError extends Error {
   }
 }
 
-export class CompileError extends Error {
-  constructor(
-    message: string,
-    public expression: string,
-    public location: Location | null,
-    options?: ErrorOptions
-  ) {
-    super(message, options)
-    this.name = this.constructor.name
-  }
-}
+/** Runtime error thrown when expression evaluation fails (e.g. unknown identifier). */
+export class ExpressionError extends SimplexError {}
+
+/** Error thrown during compilation (e.g. duplicate let bindings, invalid keys). */
+export class CompileError extends SimplexError {}
 
+/** TypeError with expected-vs-actual type info (e.g. "Expected number, but got string"). */
 export class UnexpectedTypeError extends TypeError {
   I18N_STRING = 'UNEXPECTED_TYPE'
 

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './compiler.js'
+export * from './error-mapping.js'
 export * from './errors.js'
 export * from './simplex-tree.js'
 export * from './tools/index.js'

package/src/simplex-tree.ts

@@ -7,9 +7,11 @@ export type Expression =
   | LogicalExpression
   | LiteralExpression
   | MemberExpression
+  | NonNullAssertExpression
   | ObjectExpression
   | NullishCoalescingExpression
   | PipeSequence
+  | TemplateLiteralExpression
   | TopicReference
   | UnaryExpression
   | LambdaExpression
@@ -54,19 +56,26 @@ export interface PropertyAssignment {
   type: 'Property'
   key: Expression
   value: Expression
+  computed: boolean
   kind: 'init'
   location: Location
 }
 
+export interface SpreadElement {
+  type: 'SpreadElement'
+  argument: Expression
+  location: Location
+}
+
 export interface ObjectExpression {
   type: 'ObjectExpression'
-  properties: PropertyAssignment[]
+  properties: (PropertyAssignment | SpreadElement)[]
   location: Location
 }
 
 export interface ArrayExpression {
   type: 'ArrayExpression'
-  elements: (Expression | null)[]
+  elements: (Expression | SpreadElement | null)[]
   location: Location
 }
 
@@ -188,3 +197,22 @@ export interface LetExpression {
   expression: Expression
   location: Location
 }
+
+export interface TemplateElement {
+  value: string
+  location: Location
+}
+
+export interface NonNullAssertExpression {
+  type: 'NonNullAssertExpression'
+  expression: Expression
+  location: Location
+}
+
+export interface TemplateLiteralExpression {
+  type: 'TemplateLiteral'
+  tag: Expression | null
+  quasis: TemplateElement[]
+  expressions: Expression[]
+  location: Location
+}

package/src/simplex.peggy

@@ -271,6 +271,47 @@ SingleStringCharacter
   / "\\" sequence:EscapeSequence { return sequence; }
   / LineContinuation
 
+TemplateLiteral "template literal"
+  = "`" head:TemplateCharacter* parts:TemplatePart* "`" {
+      var quasis = [];
+      var expressions = [];
+
+      quasis.push({
+        value: head.join(""),
+        location: getLocation(location())
+      });
+
+      for (var i = 0; i < parts.length; i++) {
+        expressions.push(parts[i].expression);
+        quasis.push({
+          value: (parts[i].suffix || []).join(""),
+          location: getLocation(location())
+        });
+      }
+
+      return {
+        type: "TemplateLiteral",
+        tag: null,
+        quasis: quasis,
+        expressions: expressions,
+        location: getLocation(location())
+      };
+    }
+
+TemplatePart
+  = "${" __ expression:Expression __ "}" suffix:TemplateCharacter* {
+      return { expression: expression, suffix: suffix };
+    }
+
+TemplateCharacter
+  = "\\" sequence:TemplateEscapeSequence { return sequence; }
+  / !("`" / "${" / "\\") SourceCharacter { return text(); }
+
+TemplateEscapeSequence
+  = "`" { return "`"; }
+  / "$" { return "$"; }
+  / EscapeSequence
+
 LineContinuation
   = "\\" LineTerminatorSequence { return ""; }
 
@@ -381,6 +422,7 @@ PrimaryExpression
   = Identifier
   / Literal
   / TopicReference
+  / TemplateLiteral
   / ArrayLiteral
   / ObjectLiteral
   / "(" __ expression:Expression __ ")" { return expression; }
@@ -410,12 +452,12 @@ ArrayLiteral
 
 ElementList
   = head:(
-      elision:(Elision __)? element:Expression {
+      elision:(Elision __)? element:(SpreadElement / Expression) {
         return optionalList(extractOptional(elision, 0)).concat(element);
       }
     )
     tail:(
-      __ "," __ elision:(Elision __)? element:Expression {
+      __ "," __ elision:(Elision __)? element:(SpreadElement / Expression) {
         return optionalList(extractOptional(elision, 0)).concat(element);
       }
     )*
@@ -452,12 +494,33 @@ PropertyNameAndValueList
       return buildList(head, tail, 3);
     }
 
+SpreadElement
+  = "..." __ argument:Expression {
+      return {
+        type: "SpreadElement",
+        argument: argument,
+        location: getLocation(location())
+      };
+    }
+
 PropertyAssignment
-  = key:PropertyName __ ":" __ value:Expression {
+  = SpreadElement
+  / key:PropertyName __ ":" __ value:Expression {
+      return {
+        type: "Property",
+        key: key,
+        value: value,
+        computed: false,
+        kind: "init",
+        location: getLocation(location())
+      };
+    }
+  / "[" __ key:Expression __ "]" __ ":" __ value:Expression {
       return {
         type: "Property",
         key: key,
         value: value,
+        computed: true,
         kind: "init",
         location: getLocation(location())
       };
@@ -488,9 +551,31 @@ MemberExpression
             property: property, computed: false, extension: true, location: getLocation(location())
           };
         }
+      / __ template:TemplateLiteral {
+          return {
+            tagged: true, template: template, location: getLocation(location())
+          };
+        }
+      / "!" !"=" {
+          return {
+            nonNullAssert: true, location: getLocation(location())
+          };
+        }
     )*
     {
       return tail.reduce(function(result, element) {
+        if (element.tagged) {
+          element.template.tag = result;
+          element.template.location = getLocation(location());
+          return element.template;
+        }
+        if (element.nonNullAssert) {
+          return {
+            type: "NonNullAssertExpression",
+            expression: result,
+            location: element.location
+          };
+        }
         return {
           type: "MemberExpression",
           object: result,
@@ -534,12 +619,44 @@ CallExpression
             type: "MemberExpression",
             property: property,
             computed: false,
+            extension: false,
+            location: getLocation(location())
+          };
+        }
+      / __ "::" __ property:IdentifierName {
+          return {
+            type: "MemberExpression",
+            property: property,
+            computed: false,
+            extension: true,
             location: getLocation(location())
           };
         }
+      / __ template:TemplateLiteral {
+          return {
+            tagged: true, template: template, location: getLocation(location())
+          };
+        }
+      / "!" !"=" {
+          return {
+            nonNullAssert: true, location: getLocation(location())
+          };
+        }
     )*
     {
       return tail.reduce(function(result, element) {
+        if (element.tagged) {
+          element.template.tag = result;
+          element.template.location = getLocation(location());
+          return element.template;
+        }
+        if (element.nonNullAssert) {
+          return {
+            type: "NonNullAssertExpression",
+            expression: result,
+            location: element.location
+          };
+        }
         element[TYPES_TO_PROPERTY_NAMES[element.type]] = result;
 
         return element;

package/src/tools/index.ts

@@ -1,31 +1,18 @@
-export * from './cast.js'
-export * from './ensure.js'
-export * from './guards.js'
-
-// eslint-disable-next-line @typescript-eslint/unbound-method
-const toString = Object.prototype.toString
+import { UnexpectedTypeError } from '../errors.js'
 
 /**
- * Converts instances of Number, String and Boolean to primitives
+ * Alias for `Object.prototype.toString`
  */
-export function unbox(val: unknown) {
-  if (typeof val !== 'object' || val === null) return val
-
-  const objConstructor = val.constructor
-
-  if (
-    objConstructor === Number ||
-    objConstructor === String ||
-    objConstructor === Boolean
-  ) {
-    return val.valueOf()
-  }
-
-  return val
-}
+// eslint-disable-next-line @typescript-eslint/unbound-method
+export const objToStringAlias = Object.prototype.toString
 
 /**
- * Returns more specific type of a value
+ * The method is needed to obtain the most specific readable data type.
+ *
+ * *Usage note:* Type handling, from a performance perspective, should be done
+ * in a targeted manner. It is not possible to replace specific checks like typeof
+ * `some === "number"` or `Num.isFinite(some)` with a universal
+ * `typeOf(some) === "FiniteNumber"`.
  */
 export function typeOf(val: unknown) {
   const type = typeof val
@@ -38,8 +25,114 @@ export function typeOf(val: unknown) {
   }
 
   if (type === 'object') {
-    return toString.call(val).slice(8, -1)
+    return objToStringAlias.call(val).slice(8, -1)
   }
 
   return type
 }
+
+// --- Guards ---
+
+/** Check if value is a plain object (not Array, Map, etc.). */
+export function isObject(val: unknown): val is object {
+  return objToStringAlias.call(val) === '[object Object]'
+}
+
+// Boxed primitives (new String, etc.) are intentionally not handled — they
+// cannot originate from SimplEx expressions and are not worth the overhead.
+export function isSimpleValue(
+  val: unknown
+): val is number | string | boolean | bigint | null | undefined {
+  const type = typeof val
+
+  if (
+    type === 'string' ||
+    type === 'number' ||
+    type === 'boolean' ||
+    type === 'bigint'
+  ) {
+    return true
+  }
+
+  if (val == null) return true
+
+  return false
+}
+
+// --- Cast ---
+
+/** Coerce any value to boolean (standard JS truthiness). */
+export function castToBoolean(val: unknown): boolean {
+  // Boxed primitives (new String, etc.) are intentionally not handled — see isSimpleValue comment.
+  return Boolean(val)
+}
+
+/** Coerce value to string; objects use Object.prototype.toString. */
+export function castToString(val: unknown): string {
+  const type = typeof val
+
+  // Boxed primitives (new String, etc.) are intentionally not handled — see isSimpleValue comment.
+  if (type === 'string') return val as string
+  if (
+    val == null ||
+    type === 'number' ||
+    type === 'boolean' ||
+    type === 'bigint'
+  ) {
+    return String(val)
+  }
+
+  return objToStringAlias.call(val)
+}
+
+// --- Ensure ---
+
+/** Validate that value is a finite number or bigint; throw UnexpectedTypeError otherwise. */
+export function ensureNumber(val: unknown): number | bigint {
+  if (typeof val === 'number' && Number.isFinite(val)) {
+    return val
+  }
+
+  if (typeof val === 'bigint') {
+    return val
+  }
+
+  // Boxed primitives (new Number, etc.) are intentionally not handled — see isSimpleValue comment.
+  throw new UnexpectedTypeError(['number', 'bigint'], val)
+}
+
+/** Validate that value is a function; throw UnexpectedTypeError otherwise. */
+export function ensureFunction(val: unknown): Function {
+  if (typeof val === 'function') return val
+  throw new UnexpectedTypeError(['function'], val)
+}
+
+/** Validate that value is a plain object; throw UnexpectedTypeError otherwise. */
+export function ensureObject(val: unknown): object {
+  if (isObject(val)) return val
+  throw new UnexpectedTypeError(['object'], val)
+}
+
+/** Validate that value is an array; throw UnexpectedTypeError otherwise. */
+export function ensureArray(val: unknown): unknown[] {
+  if (Array.isArray(val)) return val
+  throw new UnexpectedTypeError(['Array'], val)
+}
+
+/** Validate that value is comparable (<, >, <=, >=); must be number, bigint, or string. */
+export function ensureRelationalComparable(
+  val: unknown
+): number | string | bigint {
+  // Boxed primitives (new String, etc.) are intentionally not handled — see isSimpleValue comment.
+  const type = typeof val
+
+  if (
+    (type === 'number' && Number.isNaN(val) === false) ||
+    type === 'string' ||
+    type === 'bigint'
+  ) {
+    return val as number | string | bigint
+  }
+
+  throw new UnexpectedTypeError(['number', 'bigint', 'string'], val)
+}