refactor: migrate source to TypeScript

Eid, exceptions, preconditions rewritten as typed classes.
ES2022 Error.cause support in all exception constructors.
tryToExecute preserves original error as cause.

Assisted-by: 🤖 claude-opus-4-6@default

Author: cardil

src/eid.ts

@@ -0,0 +1,201 @@
+/*
+ * Copyright 2016 Wave Software
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export interface UniqIdGenerator {
+  generateUniqId(): string;
+}
+
+class JFormatter {
+  private readonly template: string;
+
+  constructor(template: string) {
+    this.template = template;
+  }
+
+  format(args: unknown[]): string {
+    const regex = /%s/;
+    const reducer = (p: string, c: unknown): string => p.replace(regex, String(c));
+    return args.reduce(reducer, this.template) as string;
+  }
+}
+
+class MathRandom {
+  private static readonly LONG_MAX = 2 ** 53 - 1;
+  private static readonly LONG_MIN = -1 * 2 ** 53;
+
+  nextLong(): number {
+    return this.nextNumber(MathRandom.LONG_MIN, MathRandom.LONG_MAX);
+  }
+
+  nextInt(max: number): number {
+    return this.nextNumber(0, max);
+  }
+
+  nextNumber(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+}
+
+class StdUniqIdGenerator implements UniqIdGenerator {
+  private static readonly BASE36 = 36;
+  private static readonly INTEGER_MAX_VALUE = 2 ** 31;
+  private static readonly MIN_6_CHAR_HASH = 60466177; // for '100001' in base36
+
+  private readonly padding: string;
+  private readonly generator: MathRandom;
+
+  constructor() {
+    this.generator = new MathRandom();
+    this.padding = this.generator
+      .nextNumber(StdUniqIdGenerator.MIN_6_CHAR_HASH, StdUniqIdGenerator.INTEGER_MAX_VALUE)
+      .toString(StdUniqIdGenerator.BASE36);
+  }
+
+  generateUniqId(): string {
+    const first = Math.abs(this.generator.nextLong() + 1);
+    const second = Math.abs(this.generator.nextInt(StdUniqIdGenerator.INTEGER_MAX_VALUE));
+    const calc = first + second;
+    const hash = (Math.abs(calc) % StdUniqIdGenerator.INTEGER_MAX_VALUE).toString(
+      StdUniqIdGenerator.BASE36,
+    );
+    return String(this.padding + hash).slice(-6);
+  }
+}
+
+const DEFAULT_FORMAT = "[%s]<%s>";
+const DEFAULT_REF_FORMAT = "[%s|%s]<%s>";
+const DEFAULT_MESSAGE_FORMAT = "%s => %s";
+const DEFAULT_UNIQ_ID_GENERATOR: UniqIdGenerator = new StdUniqIdGenerator();
+
+const FORMAT_NUM_SPEC = 2;
+const REF_FORMAT_NUM_SPEC = 3;
+const MESSAGE_FORMAT_NUM_SPEC = 2;
+
+interface EidState {
+  format: string;
+  refFormat: string;
+  messageFormat: string;
+  uniqIdGenerator: UniqIdGenerator;
+}
+
+const EidInternal: EidState = {
+  format: DEFAULT_FORMAT,
+  refFormat: DEFAULT_REF_FORMAT,
+  messageFormat: DEFAULT_MESSAGE_FORMAT,
+  uniqIdGenerator: DEFAULT_UNIQ_ID_GENERATOR,
+};
+
+function validateFormat(format: string | null | undefined, numSpecifiers: number): void {
+  if (format === null || format === undefined) {
+    throw new TypeError("Format can't be null, but just received one");
+  }
+  const specifiers: string[] = [];
+  for (let i = 0; i < numSpecifiers; i++) {
+    specifiers.push(`${i}-test-id`);
+  }
+  const formatted = new JFormatter(format).format(specifiers);
+  for (const specifier of specifiers) {
+    if (formatted.indexOf(specifier) === -1) {
+      throw new TypeError(
+        `Given format contains to little format specifiers, expected ${numSpecifiers} but given "${format}"`,
+      );
+    }
+  }
+}
+
+/**
+ * Exception identifier for all Eid Runtime Exceptions.
+ *
+ * This class shouldn't be used in any public API or library. It is designed
+ * to be used for in-house development of end user applications which will
+ * report Bugs in standardized error pages or post them to issue tracker.
+ */
+export class Eid {
+  static readonly DEFAULT_FORMAT: string = DEFAULT_FORMAT;
+  static readonly DEFAULT_REF_FORMAT: string = DEFAULT_REF_FORMAT;
+  static readonly DEFAULT_MESSAGE_FORMAT: string = DEFAULT_MESSAGE_FORMAT;
+  static readonly DEFAULT_UNIQ_ID_GENERATOR: UniqIdGenerator = DEFAULT_UNIQ_ID_GENERATOR;
+
+  private readonly id: string;
+  private readonly ref: string;
+  private readonly uniq: string;
+
+  constructor(id: string, ref?: string | null) {
+    this.id = id;
+    this.ref = ref === null || ref === undefined ? "" : ref;
+    this.uniq = EidInternal.uniqIdGenerator.generateUniqId();
+  }
+
+  toString(): string {
+    if (this.ref === "") {
+      return new JFormatter(EidInternal.format).format([this.id, this.uniq]);
+    }
+    return new JFormatter(EidInternal.refFormat).format([this.id, this.ref, this.uniq]);
+  }
+
+  getId(): string {
+    return this.id;
+  }
+
+  getRef(): string {
+    return this.ref;
+  }
+
+  getUniq(): string {
+    return this.uniq;
+  }
+
+  makeLogMessage(logMessageFormat: string, ...params: unknown[]): string {
+    const message = new JFormatter(logMessageFormat).format(params);
+    return new JFormatter(Eid.getMessageFormat()).format([this.toString(), message]);
+  }
+
+  static setFormat(format: string): string {
+    validateFormat(format, FORMAT_NUM_SPEC);
+    const previously = EidInternal.format;
+    EidInternal.format = format;
+    return previously;
+  }
+
+  static setRefFormat(refFormat: string): string {
+    validateFormat(refFormat, REF_FORMAT_NUM_SPEC);
+    const previously = EidInternal.refFormat;
+    EidInternal.refFormat = refFormat;
+    return previously;
+  }
+
+  static setMessageFormat(format: string): string {
+    validateFormat(format, MESSAGE_FORMAT_NUM_SPEC);
+    const oldFormat = EidInternal.messageFormat;
+    EidInternal.messageFormat = format;
+    return oldFormat;
+  }
+
+  static getMessageFormat(): string {
+    return EidInternal.messageFormat;
+  }
+
+  static setUniqIdGenerator(uniqIdGenerator: UniqIdGenerator): UniqIdGenerator {
+    if (uniqIdGenerator === null || uniqIdGenerator === undefined) {
+      throw new TypeError("Unique ID generator can't be null, but given one");
+    }
+    const previous = EidInternal.uniqIdGenerator;
+    EidInternal.uniqIdGenerator = uniqIdGenerator;
+    return previous;
+  }
+}
+
+export default Eid;

src/exceptions.ts

@@ -0,0 +1,131 @@
+/*
+ * Copyright 2016 Wave Software
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Eid } from "./eid";
+
+function prepareMessage(eid: Eid, message: string | undefined): string {
+  return message !== undefined ? `${eid} ${message}` : String(eid);
+}
+
+function validateEid(eid: string | Eid | undefined): Eid {
+  if (eid === undefined) {
+    throw new TypeError(
+      "You need to provide an valid Eid number to EidRuntimeExceptions, but given undefined",
+    );
+  }
+  if (!(eid instanceof Eid)) {
+    return new Eid(String(eid));
+  }
+  return eid;
+}
+
+interface ErrorWithCaptureStackTrace {
+  captureStackTrace?(targetObject: object, constructorOpt?: unknown): void;
+}
+
+function correctStackTrace(target: Error, ctor: unknown): void {
+  const ErrorCtor = Error as unknown as ErrorWithCaptureStackTrace;
+  if (typeof ErrorCtor.captureStackTrace === "function") {
+    ErrorCtor.captureStackTrace(target, ctor);
+  } /* v8 ignore start -- legacy fallback for environments without Error.captureStackTrace */ else {
+    const stringified = target.toString();
+    let st: string = new Error().stack ?? stringified;
+    if (typeof st !== "string") {
+      st = stringified;
+    }
+    if (st.indexOf(stringified) < 0) {
+      st = st.replace(/^(?:Error\n)?/, `${stringified}\n`).trim();
+    }
+    target.stack = st;
+  } /* v8 ignore stop */
+}
+
+/**
+ * Baseline of all Eid runtime exception classes.
+ *
+ * This class shouldn't be used in any public API or library. It is designed
+ * to be used for in-house development of end user applications which will
+ * report Bugs in standardized error pages or post them to issue tracker.
+ */
+export class EidRuntimeException extends Error {
+  readonly eid: Eid;
+
+  constructor(eid: string | Eid | undefined, message?: string, cause?: unknown) {
+    const checkedEid = validateEid(eid);
+    const fullMessage = prepareMessage(checkedEid, message);
+    super(fullMessage, cause !== undefined ? { cause } : undefined);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "EidRuntimeException";
+    this.eid = checkedEid;
+    correctStackTrace(this, EidRuntimeException);
+  }
+}
+
+/**
+ * Eid version of NullPointerException.
+ *
+ * This class shouldn't be used in any public API or library.
+ */
+export class EidNullPointerException extends EidRuntimeException {
+  constructor(eid: string | Eid | undefined, message?: string, cause?: unknown) {
+    super(eid, message, cause);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "EidNullPointerException";
+    correctStackTrace(this, EidNullPointerException);
+  }
+}
+
+/**
+ * Eid version of IllegalArgumentException.
+ *
+ * This class shouldn't be used in any public API or library.
+ */
+export class EidIllegalArgumentException extends EidRuntimeException {
+  constructor(eid: string | Eid | undefined, message?: string, cause?: unknown) {
+    super(eid, message, cause);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "EidIllegalArgumentException";
+    correctStackTrace(this, EidIllegalArgumentException);
+  }
+}
+
+/**
+ * Eid version of IllegalStateException.
+ *
+ * This class shouldn't be used in any public API or library.
+ */
+export class EidIllegalStateException extends EidRuntimeException {
+  constructor(eid: string | Eid | undefined, message?: string, cause?: unknown) {
+    super(eid, message, cause);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "EidIllegalStateException";
+    correctStackTrace(this, EidIllegalStateException);
+  }
+}
+
+/**
+ * Eid version of IndexOutOfBoundsException.
+ *
+ * This class shouldn't be used in any public API or library.
+ */
+export class EidIndexOutOfBoundsException extends EidRuntimeException {
+  constructor(eid: string | Eid | undefined, message?: string, cause?: unknown) {
+    super(eid, message, cause);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "EidIndexOutOfBoundsException";
+    correctStackTrace(this, EidIndexOutOfBoundsException);
+  }
+}

src/index.ts

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2016 Wave Software
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { Eid } from "./eid";
+export type { UniqIdGenerator } from "./eid";
+export {
+  EidRuntimeException,
+  EidNullPointerException,
+  EidIllegalArgumentException,
+  EidIllegalStateException,
+  EidIndexOutOfBoundsException,
+} from "./exceptions";
+export { EidPreconditions } from "./preconditions";
+
+import { Eid } from "./eid";
+import {
+  EidIllegalArgumentException,
+  EidIllegalStateException,
+  EidIndexOutOfBoundsException,
+  EidNullPointerException,
+  EidRuntimeException,
+} from "./exceptions";
+import { EidPreconditions } from "./preconditions";
+
+// Backward compatibility: attach preconditions and exceptions to Eid
+const preconditions = EidPreconditions;
+const exceptions = {
+  EidRuntimeException,
+  EidNullPointerException,
+  EidIllegalArgumentException,
+  EidIllegalStateException,
+  EidIndexOutOfBoundsException,
+};
+
+export { preconditions, exceptions };
+export default Eid;