@dusted/anqst 1.0.0 → 1.5.0

package/dist/src/codecgenerators/basecodecemitters/number/decoder.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Base codec emitter (decode): base93 blob → TypeScript `number`, C++ `double`.
+ * Reconstructs IEEE 754 binary64 from eight decoded bytes (platform-native order).
+ * See RefinedSpecs/Codecs/Number_number_Codec.md and AnQst-Opaque-Wire-Contract.md §6.4.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numberDecoderEmitter = exports.descriptor = void 0;
+const comments_1 = require("../shared/comments");
+const fixedwidth_1 = require("../shared/fixedwidth");
+const encoder_1 = require("./encoder");
+Object.defineProperty(exports, "descriptor", { enumerable: true, get: function () { return encoder_1.descriptor; } });
+const strategyComment = (0, comments_1.emitStrategyComment)("Base codec emitter (decode): AnQst.Type.number / double", [
+    "Decodes base93 to bytes, then Float64Array (TS) or std::memcpy (C++).",
+    "Expects base93Decode in scope; standalone payloads are exactly 10 characters.",
+    "Round-trips all IEEE special values and distinct NaN payloads when produced by the encoder."
+]);
+exports.numberDecoderEmitter = {
+    descriptor: encoder_1.descriptor,
+    emitTsDecoder() {
+        return `${strategyComment}\n\n${(0, fixedwidth_1.emitTsFixedWidthStandaloneDecoder)("decodeAnQstNumber", encoder_1.descriptor.fixedWidth)}`;
+    },
+    emitCppDecoder() {
+        return `${strategyComment}\n\n${(0, fixedwidth_1.emitCppFixedWidthStandaloneDecoder)("decodeAnQstNumber", encoder_1.descriptor.fixedWidth)}`;
+    }
+};

package/dist/src/codecgenerators/basecodecemitters/number/encoder.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Base codec emitter (encode): AnQst.Type.number ↔ TypeScript `number`, C++ `double`.
+ * Standalone wire shape is one base93 string of length 10 (8 IEEE 754 binary64 bytes).
+ * See RefinedSpecs/Codecs/Number_number_Codec.md and AnQst-Codec-Design-Principles.md §4.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numberEncoderEmitter = exports.descriptor = void 0;
+const comments_1 = require("../shared/comments");
+const fixedwidth_1 = require("../shared/fixedwidth");
+const fixedWidth = {
+    byteWidth: 8,
+    tsViewCtor: "Float64Array",
+    cppType: "double"
+};
+exports.descriptor = {
+    codecId: "AnQst.Type.number",
+    specPath: "RefinedSpecs/Codecs/Number_number_Codec.md",
+    tsType: "number",
+    cppType: "double",
+    wireCategory: "fixed-width-scalar",
+    strategySummary: "IEEE 754 binary64: 8 platform-native bytes packed via base93 (10 characters standalone).",
+    fixedWidth
+};
+const strategyComment = (0, comments_1.emitStrategyComment)("Base codec emitter (encode): AnQst.Type.number / double", [
+    "Uses Float64Array (TS) or std::memcpy (C++) for platform-native IEEE 754 bytes.",
+    "Emits base93 via shared fixed-width standalone helper (expects base93Encode in scope).",
+    "Preserves all bit patterns including ±0, NaN, ±Infinity, subnormals."
+]);
+exports.numberEncoderEmitter = {
+    descriptor: exports.descriptor,
+    emitTsEncoder() {
+        return `${strategyComment}\n\n${(0, fixedwidth_1.emitTsFixedWidthStandaloneEncoder)("encodeAnQstNumber", fixedWidth)}`;
+    },
+    emitCppEncoder() {
+        return `${strategyComment}\n\n${(0, fixedwidth_1.emitCppFixedWidthStandaloneEncoder)("encodeAnQstNumber", fixedWidth)}`;
+    }
+};

package/dist/src/codecgenerators/basecodecemitters/shared/comments.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitStrategyComment = emitStrategyComment;
+function emitStrategyComment(title, bullets) {
+    const lines = [
+        "/**",
+        ` * ${title}`,
+        " *",
+        ...bullets.map((bullet) => ` * - ${bullet}`),
+        " */"
+    ];
+    return lines.join("\n");
+}

package/dist/src/codecgenerators/basecodecemitters/shared/contracts.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/codecgenerators/basecodecemitters/shared/fixedwidth.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitTsFixedWidthStandaloneEncoder = emitTsFixedWidthStandaloneEncoder;
+exports.emitTsFixedWidthStandaloneDecoder = emitTsFixedWidthStandaloneDecoder;
+exports.emitCppFixedWidthStandaloneEncoder = emitCppFixedWidthStandaloneEncoder;
+exports.emitCppFixedWidthStandaloneDecoder = emitCppFixedWidthStandaloneDecoder;
+function tsScalarBufferInit(descriptor, valueExpr) {
+    return [
+        `const buf = new ArrayBuffer(${descriptor.byteWidth});`,
+        `new ${descriptor.tsViewCtor}(buf)[0] = ${valueExpr};`,
+        "const bytes = new Uint8Array(buf);"
+    ];
+}
+function tsScalarBufferRead(descriptor, bytesExpr) {
+    return [
+        `const buf = new ArrayBuffer(${descriptor.byteWidth});`,
+        `new Uint8Array(buf).set(${bytesExpr});`,
+        `return new ${descriptor.tsViewCtor}(buf)[0];`
+    ];
+}
+function emitTsFixedWidthStandaloneEncoder(functionName, descriptor, valueExpr = "value") {
+    const lines = [
+        `function ${functionName}(value) {`,
+        ...tsScalarBufferInit(descriptor, valueExpr).map((line) => `  ${line}`),
+        "  return base93Encode(bytes);",
+        "}"
+    ];
+    return lines.join("\n");
+}
+function emitTsFixedWidthStandaloneDecoder(functionName, descriptor) {
+    const lines = [
+        `function ${functionName}(encoded) {`,
+        "  const bytes = base93Decode(encoded);",
+        ...tsScalarBufferRead(descriptor, "bytes").map((line) => `  ${line}`),
+        "}"
+    ];
+    return lines.join("\n");
+}
+function emitCppFixedWidthStandaloneEncoder(functionName, descriptor) {
+    return `inline std::string ${functionName}(const ${descriptor.cppType}& value) {
+  std::array<std::uint8_t, ${descriptor.byteWidth}> bytes{};
+  std::memcpy(bytes.data(), &value, ${descriptor.byteWidth});
+  return base93Encode(std::vector<std::uint8_t>(bytes.begin(), bytes.end()));
+}`;
+}
+function emitCppFixedWidthStandaloneDecoder(functionName, descriptor) {
+    return `inline ${descriptor.cppType} ${functionName}(const std::string& encoded) {
+  const std::vector<std::uint8_t> bytes = base93Decode(encoded);
+  ${descriptor.cppType} value{};
+  std::memcpy(&value, bytes.data(), ${descriptor.byteWidth});
+  return value;
+}`;
+}

package/dist/src/codecgenerators/basecodecemitters/shared/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./comments"), exports);
+__exportStar(require("./contracts"), exports);
+__exportStar(require("./fixedwidth"), exports);
+__exportStar(require("./positionalBase93"), exports);
+__exportStar(require("./rawbytes"), exports);

package/dist/src/codecgenerators/basecodecemitters/shared/positionalBase93.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitPositionalBase93CountEncoder = emitPositionalBase93CountEncoder;
+exports.emitPositionalBase93CountDecoder = emitPositionalBase93CountDecoder;
+exports.emitPositionalBase93CountCppFunctions = emitPositionalBase93CountCppFunctions;
+const base93_1 = require("../../../base93");
+function emitPositionalBase93CountEncoder(functionName = "encodeBase93Count") {
+    return `function ${functionName}(value) {
+var A = "${base93_1.BASE93_ALPHABET}", v = value >>> 0, out = "";
+if (v === 0) return A[0];
+while (v > 0) {
+  out = A[v % 93] + out;
+  v = (v / 93) | 0;
+}
+return out;
+}`;
+}
+function emitPositionalBase93CountDecoder(functionName = "decodeBase93Count") {
+    return `function ${functionName}(value) {
+var n = value.length, acc = 0, i, c;
+for (i = 0; i < n; i++) {
+  c = value.charCodeAt(i);
+  acc = acc * 93 + c - 32 - (c > 34) - (c > 92);
+}
+return acc >>> 0;
+}`;
+}
+function emitPositionalBase93CountCppFunctions() {
+    return `inline std::string encodeBase93Count(std::uint32_t value) {
+  static constexpr char A[] = "${base93_1.BASE93_ALPHABET}";
+  if (value == 0u) return std::string(1, A[0]);
+  std::string out;
+  while (value > 0u) {
+    out.insert(out.begin(), A[value % 93u]);
+    value /= 93u;
+  }
+  return out;
+}
+
+inline std::uint32_t decodeBase93Count(const std::string& value) {
+  std::uint32_t acc = 0;
+  for (char c : value) {
+    const unsigned char uc = static_cast<unsigned char>(c);
+    acc = acc * 93u + static_cast<std::uint32_t>(uc - 32 - (uc > 34) - (uc > 92));
+  }
+  return acc;
+}`;
+}

package/dist/src/codecgenerators/basecodecemitters/shared/rawbytes.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitTsRawByteStandaloneEncoder = emitTsRawByteStandaloneEncoder;
+exports.emitTsRawByteStandaloneDecoder = emitTsRawByteStandaloneDecoder;
+exports.emitCppRawByteStandaloneEncoder = emitCppRawByteStandaloneEncoder;
+exports.emitCppRawByteStandaloneDecoder = emitCppRawByteStandaloneDecoder;
+function emitTsRawByteStandaloneEncoder(functionName, valueToBytesExpr) {
+    return `function ${functionName}(value) {
+  const bytes = ${valueToBytesExpr};
+  return base93Encode(bytes);
+}`;
+}
+function emitTsRawByteStandaloneDecoder(functionName, bytesToValueExpr) {
+    return `function ${functionName}(encoded) {
+  const bytes = base93Decode(encoded);
+  return ${bytesToValueExpr};
+}`;
+}
+function emitCppRawByteStandaloneEncoder(functionName, valueToBytesExpr) {
+    return `inline std::string ${functionName}(const QByteArray& value) {
+  const std::vector<std::uint8_t> bytes = ${valueToBytesExpr};
+  return base93Encode(bytes);
+}`;
+}
+function emitCppRawByteStandaloneDecoder(functionName, bytesToValueExpr) {
+    return `inline QByteArray ${functionName}(const std::string& encoded) {
+  const std::vector<std::uint8_t> bytes = base93Decode(encoded);
+  return ${bytesToValueExpr};
+}`;
+}

package/dist/src/codecgenerators/basecodecemitters/string/decoder.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * AnQstGen base-type codec emitter for `AnQst.Type.string`.
+ * Decoder is leaf identity: the JSON string value is the domain string. See RefinedSpecs/Codecs/String_string_Codec.md.
+ * C++ integration uses QVariant::toString() / QJsonValue::toString(); portable stubs below use std::string for tests without Qt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decoder = exports.descriptor = void 0;
+const comments_1 = require("../shared/comments");
+exports.descriptor = {
+    codecId: "string",
+    specPath: "RefinedSpecs/Codecs/String_string_Codec.md",
+    tsType: "string",
+    cppType: "QString",
+    wireCategory: "string",
+    strategySummary: "Native JSON string; leaf identity encode/decode; no base93."
+};
+const TS_FN = "decodeAnqstBase_string";
+const CPP_FN = "decodeAnqstBase_string";
+exports.decoder = {
+    descriptor: exports.descriptor,
+    emitTsDecoder() {
+        return [
+            (0, comments_1.emitStrategyComment)("AnQst string decoder (identity)", [
+                "Interprets the wire JSON string as the domain value; no transform.",
+                "No base93 decode path for string positions."
+            ]),
+            `function ${TS_FN}(wire) {`,
+            "  return wire;",
+            "}"
+        ].join("\n");
+    },
+    emitCppDecoder() {
+        return [
+            (0, comments_1.emitStrategyComment)("AnQst string decoder (identity, portable stub)", [
+                "QString via QJsonValue::toString() at integration; std::string passthrough here for generator tests without Qt."
+            ]),
+            `inline std::string ${CPP_FN}(const std::string& wire) {`,
+            "  return wire;",
+            "}"
+        ].join("\n");
+    }
+};

package/dist/src/codecgenerators/basecodecemitters/string/encoder.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * AnQstGen base-type codec emitter for `AnQst.Type.string`.
+ * Wire form is a native JSON string (no base93). See RefinedSpecs/Codecs/String_string_Codec.md.
+ * Integration codegen maps the C++ domain type to QString / QJsonValue; standalone C++ snippets here use std::string so unit tests compile without Qt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encoder = exports.descriptor = void 0;
+const comments_1 = require("../shared/comments");
+exports.descriptor = {
+    codecId: "string",
+    specPath: "RefinedSpecs/Codecs/String_string_Codec.md",
+    tsType: "string",
+    cppType: "QString",
+    wireCategory: "string",
+    strategySummary: "Native JSON string; leaf identity encode/decode; no base93."
+};
+const TS_FN = "encodeAnqstBase_string";
+const CPP_FN = "encodeAnqstBase_string";
+exports.encoder = {
+    descriptor: exports.descriptor,
+    emitTsEncoder() {
+        return [
+            (0, comments_1.emitStrategyComment)("AnQst string encoder (identity)", [
+                "Emits the domain string unchanged for placement in JSON (native string on the wire).",
+                "No base93; JSON serializers handle escaping of quotes, backslashes, and controls."
+            ]),
+            `function ${TS_FN}(value) {`,
+            "  return value;",
+            "}"
+        ].join("\n");
+    },
+    emitCppEncoder() {
+        return [
+            (0, comments_1.emitStrategyComment)("AnQst string encoder (identity, portable stub)", [
+                "QString / QJsonValue(value) at widget integration; std::string here for generator tests without Qt."
+            ]),
+            `inline std::string ${CPP_FN}(const std::string& value) {`,
+            "  return value;",
+            "}"
+        ].join("\n");
+    }
+};

package/dist/src/codecgenerators/basecodecemitters/stringArray/decoder.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Base codec emitter: AnQst.Type.stringArray — TypeScript/C++ decoder (standalone wire → string[] / QStringList).
+ *
+ * Standalone: if the payload is a string, it must decode to count 0 (empty array). If it is an array, the first
+ * element is the positional base93 count; the next count elements are the string values.
+ *
+ * Composite decoding is performed by the structured top-level codec: it reads the array length from blob
+ * metadata, then consumes that many consecutive strings from the flat collection (String_stringArray_Codec.md §5).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decoderEmitter = exports.descriptor = void 0;
+exports.descriptor = {
+    codecId: "stringArray",
+    specPath: "RefinedSpecs/Codecs/String_stringArray_Codec.md",
+    tsType: "string[]",
+    cppType: "QStringList",
+    wireCategory: "string-array",
+    strategySummary: "Standalone: decode first item as positional base93 count, then read that many native strings; string-only payload implies count 0. Composite: length from byte blob; strings from shared collection (structured layer)."
+};
+const TS_FN = "decodeStringArrayStandalone";
+const CPP_FN = "decodeStringArrayStandalone";
+exports.decoderEmitter = {
+    descriptor: exports.descriptor,
+    emitTsDecoder() {
+        return `function ${TS_FN}(payload) {
+  if (typeof payload === "string") {
+    var n0 = decodeBase93Count(payload);
+    if (n0 !== 0) {
+      throw new Error("stringArray standalone: string payload must encode count 0");
+    }
+    return [];
+  }
+  if (!Array.isArray(payload)) {
+    throw new Error("stringArray standalone: expected JSON string or array");
+  }
+  if (payload.length < 2) {
+    throw new Error("stringArray standalone: array payload too short");
+  }
+  var n = decodeBase93Count(String(payload[0]));
+  if (payload.length !== n + 1) {
+    throw new Error("stringArray standalone: count does not match array tail");
+  }
+  var out = new Array(n);
+  for (var i = 0; i < n; i++) {
+    var el = payload[i + 1];
+    out[i] = el == null ? "" : String(el);
+  }
+  return out;
+}`;
+    },
+    emitCppDecoder() {
+        return `inline QStringList ${CPP_FN}(const QJsonValue& payload) {
+  if (payload.isString()) {
+    const std::uint32_t n = decodeBase93Count(payload.toString().toStdString());
+    if (n != 0u) {
+      throw std::runtime_error("stringArray standalone: string payload must encode count 0");
+    }
+    return QStringList();
+  }
+  if (!payload.isArray()) {
+    throw std::runtime_error("stringArray standalone: expected JSON string or array");
+  }
+  const QJsonArray arr = payload.toArray();
+  if (arr.size() < 2) {
+    throw std::runtime_error("stringArray standalone: array payload too short");
+  }
+  const std::uint32_t n = decodeBase93Count(arr.at(0).toString().toStdString());
+  if (arr.size() != static_cast<int>(n) + 1) {
+    throw std::runtime_error("stringArray standalone: count does not match array tail");
+  }
+  QStringList out;
+  out.reserve(static_cast<int>(n));
+  for (std::uint32_t i = 0; i < n; ++i) {
+    out.append(arr.at(static_cast<int>(i + 1)).toString());
+  }
+  return out;
+}`;
+    }
+};

package/dist/src/codecgenerators/basecodecemitters/stringArray/encoder.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Base codec emitter: AnQst.Type.stringArray — TypeScript/C++ encoder (string[] / QStringList → standalone wire).
+ *
+ * Standalone: positional base93 element count as the first emission item, then native JSON string elements.
+ * Empty array: the count alone is emitted as a single string (best-case emission).
+ * Non-empty: a flat JSON array [count, ...elements] (length N+1 ≥ 2).
+ *
+ * Composite (structured top-level codec): string elements merge into the shared flat string collection; the
+ * element count is stored as fixed-width unsigned metadata (e.g. uint32) inside the byte blob, not as a
+ * separate base93 count string. See Structured_TopLevelCodec_Strategy.md §3.2 and String_stringArray_Codec.md §5.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encoderEmitter = exports.descriptor = void 0;
+exports.descriptor = {
+    codecId: "stringArray",
+    specPath: "RefinedSpecs/Codecs/String_stringArray_Codec.md",
+    tsType: "string[]",
+    cppType: "QStringList",
+    wireCategory: "string-array",
+    strategySummary: "Standalone: prepend positional base93 count string, then emit each element as a native JSON string; empty → single count string. Composite: count in byte blob as fixed-width uint; elements in shared string collection (orchestrated by structured layer)."
+};
+const TS_FN = "encodeStringArrayStandalone";
+const CPP_FN = "encodeStringArrayStandalone";
+exports.encoderEmitter = {
+    descriptor: exports.descriptor,
+    emitTsEncoder() {
+        return `function ${TS_FN}(value) {
+  var n = value.length;
+  var countStr = encodeBase93Count(n);
+  if (n === 0) {
+    return countStr;
+  }
+  var out = new Array(n + 1);
+  out[0] = countStr;
+  for (var i = 0; i < n; i++) {
+    out[i + 1] = value[i];
+  }
+  return out;
+}`;
+    },
+    emitCppEncoder() {
+        return `inline QJsonValue ${CPP_FN}(const QStringList& value) {
+  const std::uint32_t n = static_cast<std::uint32_t>(value.size());
+  const QString countStr = QString::fromStdString(encodeBase93Count(n));
+  if (n == 0u) {
+    return QJsonValue(countStr);
+  }
+  QJsonArray arr;
+  arr.append(countStr);
+  for (const QString& s : value) {
+    arr.append(QJsonValue(s));
+  }
+  return QJsonValue(arr);
+}`;
+    }
+};