@fintekkers/ledger-models 0.4.37 → 0.4.39

package/node/wrappers/util/object-types.ts

@@ -0,0 +1,207 @@
+/**
+ * Compact object type and version (LM-297), stage 1: write both forms, read the new one.
+ *
+ * Every message with `string object_class = 1` and `string version = 2` also
+ * carries `ObjectTypeProto object_type = 1001` and `uint32 version_major /
+ * version_minor / version_patch = 1002-1004`. Writers call `stamp`, which sets
+ * the strings and the new fields. Readers call `readType` / `readVersion` (or
+ * `upgrade`), which use the new fields and fall back to the deprecated strings,
+ * logging one `console.warn` per distinct pair of strings. A fallback never
+ * throws: an unknown object_class gives OBJECT_TYPE_UNKNOWN and a malformed
+ * version gives 0.0.0. Empty strings are the proto3 default and fall back
+ * silently.
+ *
+ * google-protobuf cannot read the `(legacy_object_class)` options at runtime,
+ * so the string map comes from object-type-legacy.json, generated by
+ * scripts/gen-object-type-legacy-map.py. See docs/adr/compact_object_type_and_version.md.
+ */
+import { ObjectTypeProto } from '../../fintekkers/models/util/object_type_pb';
+import legacyMirror from './object-type-legacy.json';
+
+/** Any generated message that carries object_class / version and their compact form. */
+export interface ObjectTyped {
+  getObjectClass(): string;
+  setObjectClass(value: string): unknown;
+  getVersion(): string;
+  setVersion(value: string): unknown;
+  getObjectType(): ObjectTypeProto;
+  setObjectType(value: ObjectTypeProto): unknown;
+  getVersionMajor(): number;
+  setVersionMajor(value: number): unknown;
+  getVersionMinor(): number;
+  setVersionMinor(value: number): unknown;
+  getVersionPatch(): number;
+  setVersionPatch(value: number): unknown;
+}
+
+/** [major, minor, patch], each a uint32. */
+export type Version = [number, number, number];
+
+const UINT32_MAX = 0xffffffff;
+const VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+function buildLegacyMap(): Map<string, ObjectTypeProto> {
+  const map = new Map<string, ObjectTypeProto>();
+  for (const [legacy, name] of Object.entries(legacyMirror.legacy_object_class)) {
+    if (!Object.prototype.hasOwnProperty.call(ObjectTypeProto, name)) {
+      throw new Error(`object-type-legacy.json names ${name}, which ObjectTypeProto lacks: regenerate it`);
+    }
+    map.set(legacy, ObjectTypeProto[name as keyof typeof ObjectTypeProto]);
+  }
+  return map;
+}
+
+const LEGACY = buildLegacyMap();
+const warned = new Set<string>();
+const UNKNOWN_NAME = Object.keys(ObjectTypeProto)
+  .find((name) => ObjectTypeProto[name as keyof typeof ObjectTypeProto] === ObjectTypeProto.OBJECT_TYPE_UNKNOWN) as string;
+const PREFIX = UNKNOWN_NAME.slice(0, -'UNKNOWN'.length);
+const CAMEL_BOUNDARY = /(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g;
+const ownTypes = new WeakMap<object, ObjectTypeProto>();
+
+/** The ObjectTypeProto value an object_class string stands for, or OBJECT_TYPE_UNKNOWN. */
+export function fromLegacy(objectClass: string): ObjectTypeProto {
+  return LEGACY.get(objectClass) ?? ObjectTypeProto.OBJECT_TYPE_UNKNOWN;
+}
+
+/**
+ * The ObjectTypeProto value named for a message type, or OBJECT_TYPE_UNKNOWN.
+ * Uses the enum's naming rule: `QuerySecurityRequestProto` ->
+ * OBJECT_TYPE_QUERY_SECURITY_REQUEST.
+ */
+export function ownType(messageName: string): ObjectTypeProto {
+  const base = messageName.endsWith('Proto') ? messageName.slice(0, -'Proto'.length) : messageName;
+  const name = PREFIX + base.replace(CAMEL_BOUNDARY, '_').toUpperCase();
+  return Object.prototype.hasOwnProperty.call(ObjectTypeProto, name)
+    ? ObjectTypeProto[name as keyof typeof ObjectTypeProto]
+    : ObjectTypeProto.OBJECT_TYPE_UNKNOWN;
+}
+
+/**
+ * The generated class name of `message`. google-protobuf's classes are
+ * anonymous functions, but each generated module exports its classes under
+ * the global `proto` namespace by full name, so search that.
+ */
+function messageName(ctor: object, namespace: unknown, depth = 0): string | undefined {
+  if (typeof namespace !== 'object' || namespace === null || depth > 8) return undefined;
+  for (const [key, value] of Object.entries(namespace)) {
+    if (value === ctor) return key;
+    const found = messageName(ctor, value, depth + 1);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+function ownTypeOf(message: ObjectTyped): ObjectTypeProto {
+  const ctor = message.constructor;
+  let type = ownTypes.get(ctor);
+  if (type === undefined) {
+    const name = messageName(ctor, (globalThis as { proto?: unknown }).proto);
+    type = name === undefined ? ObjectTypeProto.OBJECT_TYPE_UNKNOWN : ownType(name);
+    ownTypes.set(ctor, type);
+  }
+  return type;
+}
+
+/** '1.2.3' -> [1, 2, 3]; null unless exactly three decimal uint32 parts. */
+export function parseVersion(version: string): Version | null {
+  if (!VERSION_PATTERN.test(version)) return null;
+  const parts = version.split('.').map(Number);
+  if (parts.some((p) => p > UINT32_MAX)) return null;
+  return [parts[0], parts[1], parts[2]];
+}
+
+/**
+ * Sets object_class / version and their compact form on `message`; returns it.
+ * `objectType` is the message's own ObjectTypeProto value. `version` must be
+ * empty or three uint32 parts.
+ */
+export function stamp<T extends ObjectTyped>(message: T, objectType: ObjectTypeProto, objectClass: string, version: string): T {
+  const parts = version ? parseVersion(version) : [0, 0, 0];
+  if (parts === null) {
+    throw new Error(`version must be MAJOR.MINOR.PATCH, got '${version}'`);
+  }
+  message.setObjectClass(objectClass);
+  message.setVersion(version);
+  message.setObjectType(objectType);
+  setCompactVersion(message, parts as Version);
+  return message;
+}
+
+function setCompactVersion(message: ObjectTyped, [major, minor, patch]: Version): void {
+  message.setVersionMajor(major);
+  message.setVersionMinor(minor);
+  message.setVersionPatch(patch);
+}
+
+function compactVersion(message: ObjectTyped): Version {
+  return [message.getVersionMajor(), message.getVersionMinor(), message.getVersionPatch()];
+}
+
+function decode(message: ObjectTyped): { objectType: ObjectTypeProto; version: Version } {
+  const objectClass = message.getObjectClass();
+  const versionString = message.getVersion();
+  let objectType = message.getObjectType();
+  let version = compactVersion(message);
+  const problems: string[] = [];
+  let usedStrings = false;
+
+  if (objectType === ObjectTypeProto.OBJECT_TYPE_UNKNOWN && objectClass) {
+    usedStrings = true;
+    objectType = fromLegacy(objectClass);
+    if (objectType === ObjectTypeProto.OBJECT_TYPE_UNKNOWN) {
+      problems.push(' (unknown object_class, using OBJECT_TYPE_UNKNOWN)');
+    } else {
+      // Some strings were written on more than one message type (e.g.
+      // 'SecurityRequest' on the create and query requests): the message's
+      // own type wins over the value the string sits on.
+      const own = ownTypeOf(message);
+      if (own !== ObjectTypeProto.OBJECT_TYPE_UNKNOWN) objectType = own;
+    }
+  }
+  if (version.every((p) => p === 0) && versionString) {
+    usedStrings = true;
+    const parsed = parseVersion(versionString);
+    if (parsed === null) {
+      problems.push(' (malformed version, using 0.0.0)');
+    } else {
+      version = parsed;
+    }
+  }
+
+  const key = `${objectClass}\u0000${versionString}`;
+  if (usedStrings && !warned.has(key)) {
+    warned.add(key);
+    console.warn(
+      `${message.constructor.name} read from deprecated strings object_class='${objectClass}' ` +
+      `version='${versionString}'${problems.join('')}; re-save it to write object_type and ` +
+      'version_major/minor/patch (LM-297)');
+  }
+  return { objectType, version };
+}
+
+/** The message's ObjectTypeProto value: object_type, else the object_class string. */
+export function readType(message: ObjectTyped): ObjectTypeProto {
+  return decode(message).objectType;
+}
+
+/** The message's [major, minor, patch]: the compact fields, else the version string. */
+export function readVersion(message: ObjectTyped): Version {
+  return decode(message).version;
+}
+
+/**
+ * Fills the compact fields from the strings where they are unset; returns `message`.
+ * The strings are kept, so re-serialising writes both forms.
+ */
+export function upgrade<T extends ObjectTyped>(message: T): T {
+  const { objectType, version } = decode(message);
+  message.setObjectType(objectType);
+  setCompactVersion(message, version);
+  return message;
+}
+
+/** Forgets which strings have warned. Tests only. */
+export function resetWarningsForTests(): void {
+  warned.clear();
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fintekkers/ledger-models",
   "todo": "Replace the version with build script version number",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "ledger model protos ",
   "authors": [
     "David Doherty",

package/tsconfig.json

@@ -2,6 +2,7 @@
   "compileOnSave": true,
   "compilerOptions": {
     "target": "es2016",
+    "lib": ["es2016", "es2020.bigint", "dom"],
     "module": "commonjs",
     "declaration": true,
     "sourceMap": true,