initial commit

src/exceptions.ts

@@ -0,0 +1,21 @@
+export class AbortSubstitutionException extends Error { }
+
+export class PlaceholderException extends Error {
+  readonly #input: string;
+  readonly #pos: number;
+
+  constructor(input: string, pos: number, message?: string, cause?: any) {
+    super(message, { cause });
+
+    this.#input = input;
+    this.#pos = pos;
+  }
+
+  public get input() {
+    return this.#input;
+  }
+
+  public get position() {
+    return this.#pos;
+  }
+}

src/index.ts

@@ -0,0 +1,7 @@
+export { PlaceholderOptions, PlaceholderSubstitutor } from "./placeholder.js";
+export * from "./pattern.js";
+export * as VariableResolvers from "./resolver/index.js";
+export * from "./resolver/types.js";
+export * as UnknownVariableHandlers from "./unknown-variable-handler/index.js";
+export * from "./unknown-variable-handler/types.js";
+export * from "./exceptions.js";

src/pattern.ts

@@ -0,0 +1,17 @@
+export default class PlaceholderPattern {
+  readonly #prefix: string;
+  readonly #suffix: string;
+
+  public constructor(prefix: string, suffix: string) {
+    this.#prefix = prefix;
+    this.#suffix = suffix;
+  }
+
+  public get prefix() {
+    return this.#prefix;
+  }
+
+  public get suffix() {
+    return this.#suffix;
+  }
+}

src/placeholder.ts

@@ -0,0 +1,171 @@
+import { AbortSubstitutionException, PlaceholderException } from "./exceptions.js";
+import PlaceholderPattern from "./pattern.js";
+import { EMPTY as emptyResolver } from "./resolver/index.js";
+import { VariableResolver } from "./resolver/types.js";
+import StringSection from "./string-section.js";
+import { UnknownVariableHandler } from "./unknown-variable-handler/types.js";
+import { isDefined, Nullable } from "./utils.js";
+
+
+export type PlaceholderOptions = {
+  pattern?: PlaceholderPattern;
+  escapeChar?: string;
+  recursive?: boolean;
+  resolver?: VariableResolver;
+  unknownVariableHandler?: Nullable<UnknownVariableHandler>;
+};
+
+const DEFAULT_OPTIONS: Required<PlaceholderOptions> = {
+  pattern: new PlaceholderPattern("${", "}"),
+  escapeChar: '\\',
+  recursive: false,
+  resolver: emptyResolver,
+  unknownVariableHandler: null
+};
+
+export class PlaceholderSubstitutor {
+  readonly #pattern: PlaceholderPattern;
+  readonly #escapeChar: string;
+  readonly #recursive: boolean;
+  readonly #resolver: VariableResolver;
+  readonly #unknownVariableHandler: Nullable<UnknownVariableHandler>;
+
+  public constructor(options: PlaceholderOptions = DEFAULT_OPTIONS) {
+    this.#pattern = options.pattern ?? DEFAULT_OPTIONS.pattern;
+    this.#escapeChar = options.escapeChar ?? DEFAULT_OPTIONS.escapeChar;
+    this.#recursive = options.recursive ?? DEFAULT_OPTIONS.recursive;
+    this.#resolver = options.resolver ?? DEFAULT_OPTIONS.resolver;
+    this.#unknownVariableHandler = options.unknownVariableHandler ?? DEFAULT_OPTIONS.unknownVariableHandler;
+  }
+
+  public get pattern() {
+    return this.#pattern;
+  }
+
+  public get escapeChar() {
+    return this.#escapeChar;
+  }
+
+  public get recursive() {
+    return this.#recursive;
+  }
+
+  public get resolver() {
+    return this.#resolver;
+  }
+
+  public get unknownVariableHandler() {
+    return this.#unknownVariableHandler;
+  }
+
+  public replace(s: string): string;
+  public replace(s: Nullable<string>): Nullable<string>;
+  public replace(s: Nullable<string>) {
+    return s ? new Substitutor(this, new StringSection(s), false).replace() : s;
+  }
+}
+
+class Substitutor {
+  readonly #substitutor: PlaceholderSubstitutor;
+  readonly #input: StringSection;
+  readonly #inner: boolean;
+  #pos = 0;
+
+  constructor(substitutor: PlaceholderSubstitutor, input: StringSection, inner: boolean) {
+    this.#substitutor = substitutor;
+    this.#input = input;
+    this.#inner = inner;
+  }
+
+  replace(): string {
+    const result: string[] = [];
+
+    let escaping = false;
+    let hasSuffix = false;
+
+    while (this.#pos < this.#input.length) {
+      const c = this.#input.charAt(this.#pos);
+
+      if (escaping) {
+        result.push(c);
+        escaping = false;
+      } else if (c === this.#substitutor.escapeChar) {
+        escaping = true;
+      } else if (this.tryAdvance(this.#substitutor.pattern.prefix)) {
+        const innerSubstitutor = new Substitutor(this.#substitutor, this.#input.subSection(this.#pos), true);
+        const variable = innerSubstitutor.replace();
+
+        if (variable.length === 0) {
+          throw new PlaceholderException(this.#input.getSection(), this.#pos, "Empty variable");
+        }
+
+        const value = this.resolveVariable(variable);
+
+        if (!isDefined(value)) {
+          result.push(this.#substitutor.pattern.prefix, variable, this.#substitutor.pattern.suffix);
+        } else if (this.#substitutor.recursive) {
+          result.push(this.#substitutor.replace(value));
+        } else {
+          result.push(value);
+        }
+
+        this.#pos += innerSubstitutor.#pos;
+
+        continue;
+      } else if (this.tryAdvance(this.#substitutor.pattern.suffix)) {
+        if (this.#inner) {
+          hasSuffix = true;
+          break;
+        }
+
+        throw new PlaceholderException(this.#input.getSection(), this.#pos, "Missing prefix");
+      } else {
+        result.push(c);
+      }
+
+      this.#pos++;
+    }
+
+    if (this.#inner && !hasSuffix) {
+      throw new PlaceholderException(this.#input.getSection(), this.#pos, "Missing suffix");
+    }
+
+    return result.join("");
+  }
+
+  private continuesWith(sequence: string) {
+    return this.#input.startsWith(sequence, this.#pos);
+  }
+
+  private tryAdvance(sequence: string) {
+    const b = this.continuesWith(sequence);
+
+    if (b) {
+      this.#pos += sequence.length;
+    }
+
+    return b;
+  }
+
+  private resolveVariable(name: string) {
+    const value = this.#substitutor.resolver(name);
+
+    if (isDefined(value)) {
+      return typeof value === "string" ? value : value();
+    }
+
+    if (this.#substitutor.unknownVariableHandler) {
+      try {
+        return this.#substitutor.unknownVariableHandler(this.#substitutor, name);
+      } catch (e: any) {
+        if (e instanceof AbortSubstitutionException) {
+          throw new PlaceholderException(this.#input.getSection(), this.#pos, "Substitution aborted due to unknown variable", e);
+        }
+
+        throw new PlaceholderException(this.#input.getSection(), this.#pos, "An error occurred while handling unknown variable", e);
+      }
+    }
+
+    return null;
+  }
+}

src/resolver/index.ts

@@ -0,0 +1,30 @@
+import { isDefined, Nullable } from "../utils.js";
+import { ObjectResolver, VariableResolver, VariableValue } from "./types.js";
+
+export const EMPTY: VariableResolver = () => null;
+
+export function combine(...resolvers: VariableResolver[]) {
+  return (name: string) => {
+    for (const resolver of resolvers) {
+      const value = resolver(name);
+
+      if (isDefined(value)) {
+        return value;
+      }
+    }
+
+    return null;
+  };
+}
+
+export function map(values: Map<string, VariableValue>): VariableResolver {
+  return (name: string) => values.get(name);
+}
+
+export function object(values: Record<string, VariableValue>): VariableResolver {
+  return (name: string) => values[name];
+}
+
+export function mapper<T>(mappers: (name: string) => Nullable<ObjectResolver<T>>): (obj: T) => VariableResolver {
+  return (obj: T) => (name: string) => mappers(name)?.(obj);
+}

src/resolver/types.ts

@@ -0,0 +1,5 @@
+import { Nullable } from "../utils.js";
+
+export type VariableValue = string | (() => string);
+export type VariableResolver = (name: string) => Nullable<VariableValue>;
+export type ObjectResolver<T> = (obj: T) => Nullable<VariableValue>;

src/string-section.ts

@@ -0,0 +1,47 @@
+export default class StringSection {
+  readonly #parent: string;
+  readonly #offset: number;
+  readonly #length: number;
+
+  constructor(parent: string, offset: number = 0, length: number = parent.length - offset) {
+    if (offset < 0) {
+      throw new Error("offset < 0");
+    }
+
+    if (length < 0) {
+      throw new Error("length < 0");
+    }
+
+    if (offset + length > parent.length) {
+      throw new Error("offset + length > parent.length");
+    }
+
+    this.#parent = parent;
+    this.#offset = offset;
+    this.#length = length;
+  }
+
+  public get length() {
+    return this.#length;
+  }
+
+  public getSection() {
+    return this.substring(0);
+  }
+
+  public subSection(offset: number = 0, length: number = this.#length - offset) {
+    return new StringSection(this.#parent, this.#offset + offset, length);
+  }
+
+  public charAt(index: number) {
+    return this.#parent.charAt(this.#offset + index);
+  }
+
+  public startsWith(prefix: string, offset: number = 0) {
+    return this.#parent.startsWith(prefix, this.#offset + offset);
+  }
+
+  public substring(beginIndex: number = 0, endIndex: number = this.#length - beginIndex) {
+    return this.#parent.substring(this.#offset + beginIndex, this.#offset + endIndex);
+  }
+}

src/unknown-variable-handler/index.ts

@@ -0,0 +1,6 @@
+import { AbortSubstitutionException } from "../exceptions.js";
+import { UnknownVariableHandler } from "./types.js";
+
+export const ABORT: UnknownVariableHandler = () => {
+  throw new AbortSubstitutionException();
+};

src/unknown-variable-handler/types.ts

@@ -0,0 +1,4 @@
+import { PlaceholderSubstitutor } from "../placeholder.js";
+import { Nullable } from "../utils.js";
+
+export type UnknownVariableHandler = (substitutor: PlaceholderSubstitutor, variable: string) => Nullable<string>;

src/utils.ts

@@ -0,0 +1,5 @@
+export type Nullable<T> = T | null | undefined;
+
+export function isDefined<T>(obj: Nullable<T>): obj is T & {} {
+  return obj !== null && obj !== undefined;
+}