@fedify/vocab-runtime 2.1.0-dev.565 → 2.1.0-dev.599

package/src/decimal.test.ts

@@ -0,0 +1,90 @@
+import { deepStrictEqual, throws } from "node:assert";
+import { test } from "node:test";
+import { canParseDecimal, isDecimal, parseDecimal } from "./decimal.ts";
+import {
+  canParseDecimal as canParseDecimalFromModule,
+  isDecimal as isDecimalFromModule,
+  parseDecimal as parseDecimalFromModule,
+} from "./mod.ts";
+
+test("parseDecimal() accepts valid xsd:decimal lexical forms", () => {
+  const values = [
+    "-1.23",
+    "12678967.543233",
+    "+100000.00",
+    "210",
+    ".5",
+    "5.",
+    "0",
+    "-0.0",
+  ];
+
+  for (const value of values) {
+    deepStrictEqual(parseDecimal(value), value);
+  }
+});
+
+test("isDecimal() reports valid xsd:decimal lexical forms", () => {
+  deepStrictEqual(isDecimal("12.50"), true);
+  deepStrictEqual(isDecimal(".5"), true);
+  deepStrictEqual(isDecimal("1e3"), false);
+  deepStrictEqual(isDecimal(" 12.50 "), false);
+  deepStrictEqual(isDecimal("\t12.50\n"), false);
+});
+
+test("canParseDecimal() accepts whitespace-normalized xsd:decimal strings", () => {
+  deepStrictEqual(canParseDecimal("12.50"), true);
+  deepStrictEqual(canParseDecimal(" 12.50 "), true);
+  deepStrictEqual(canParseDecimal("\t+100000.00\r\n"), true);
+  deepStrictEqual(canParseDecimal("  .5  "), true);
+  deepStrictEqual(canParseDecimal("1e3"), false);
+  deepStrictEqual(canParseDecimal("1 2.50"), false);
+  deepStrictEqual(canParseDecimal("1\t2.50"), false);
+});
+
+test("parseDecimal() normalizes XML Schema whitespace", () => {
+  deepStrictEqual(parseDecimal("12.50"), "12.50");
+  deepStrictEqual(parseDecimal(" 12.50 "), "12.50");
+  deepStrictEqual(parseDecimal("\t+100000.00\r\n"), "+100000.00");
+  deepStrictEqual(parseDecimal("  .5  "), ".5");
+});
+
+test("parseDecimal() rejects invalid xsd:decimal lexical forms", () => {
+  const values = [
+    "",
+    ".",
+    "+",
+    "-",
+    "1e3",
+    "NaN",
+    "INF",
+    "1,2",
+    "1..2",
+    "1 2.3",
+    "1\t2.3",
+  ];
+
+  for (const value of values) {
+    throws(
+      () => parseDecimal(value),
+      {
+        name: "TypeError",
+        message: `${
+          JSON.stringify(value)
+        } is not a valid xsd:decimal lexical form.`,
+      },
+    );
+  }
+});
+
+test("parseDecimal() is exported from the package root", () => {
+  deepStrictEqual(parseDecimalFromModule("12.50"), "12.50");
+});
+
+test("canParseDecimal() is exported from the package root", () => {
+  deepStrictEqual(canParseDecimalFromModule(" 12.50 "), true);
+});
+
+test("isDecimal() is exported from the package root", () => {
+  deepStrictEqual(isDecimalFromModule("12.50"), true);
+});

package/src/decimal.ts

@@ -0,0 +1,112 @@
+const DECIMAL_PATTERN = /^(\+|-)?([0-9]+(\.[0-9]*)?|\.[0-9]+)$/;
+const XML_SCHEMA_WHITESPACE_PATTERN = /[\t\n\r ]+/g;
+
+function collapseXmlSchemaWhitespace(value: string): string {
+  return value.replace(XML_SCHEMA_WHITESPACE_PATTERN, " ").trim();
+}
+
+/**
+ * A branded string representing an `xsd:decimal` value.
+ *
+ * Unlike JavaScript's `number`, `xsd:decimal` is intended for exact decimal
+ * values such as prices, quantities, and measurements where binary
+ * floating-point rounding would be inappropriate.  Fedify therefore represents
+ * these values as validated strings at runtime while preserving a distinct
+ * TypeScript type.
+ *
+ * Values of this type must be created through {@link parseDecimal}, which
+ * validates that the string matches the XML Schema `xsd:decimal` lexical form.
+ *
+ * The runtime representation is still a plain string.  The brand exists only
+ * at the type level so APIs can distinguish arbitrary strings from validated
+ * decimal literals without introducing a decimal arithmetic dependency.
+ *
+ * Supported lexical forms include signed and unsigned integers and decimal
+ * fractions such as `"-1.23"`, `"+100000.00"`, `"210"`, `".5"`, and `"5."`.
+ * Scientific notation such as `"1e3"` and special values like `"NaN"` are
+ * rejected.  Strings with surrounding XML Schema whitespace can be normalized
+ * by {@link parseDecimal}, but values of this type are always stored in their
+ * normalized lexical form.
+ *
+ * This representation is designed to be forward-compatible with a future
+ * native decimal type if JavaScript eventually gains one, while keeping the
+ * public API semantically precise today.
+ *
+ * @since 2.1.0
+ */
+export type Decimal = string & { readonly __brand: "Decimal" };
+
+/**
+ * Checks whether a string is a valid `xsd:decimal` lexical form.
+ *
+ * This predicate checks the lexical form strictly, without applying XML Schema
+ * whitespace normalization first.  It is useful as a type guard for values
+ * that are already expected to be normalized decimal strings.
+ *
+ * @param value A candidate `xsd:decimal` lexical form.
+ * @returns `true` if the string matches the XML Schema `xsd:decimal` lexical
+ *          form, or `false` otherwise.
+ * @since 2.1.0
+ */
+export function isDecimal(value: string): value is Decimal {
+  return DECIMAL_PATTERN.test(value);
+}
+
+/**
+ * Checks whether a string can be parsed as an `xsd:decimal` lexical form.
+ *
+ * Unlike {@link isDecimal}, this predicate first applies the XML Schema
+ * `whiteSpace="collapse"` normalization step and then validates the
+ * normalized string.  This means values like `" 12.50 "` are parseable even
+ * though they are not already normalized decimal literals.
+ *
+ * @param value A candidate `xsd:decimal` lexical form.
+ * @returns `true` if the normalized string matches the XML Schema
+ *          `xsd:decimal` lexical form, or `false` otherwise.
+ * @since 2.1.0
+ */
+export function canParseDecimal(value: string): boolean {
+  return isDecimal(collapseXmlSchemaWhitespace(value));
+}
+
+/**
+ * Parses a string as an `xsd:decimal` lexical form and returns it as a
+ * branded {@link Decimal}.
+ *
+ * This function validates the input against the XML Schema `xsd:decimal`
+ * lexical space after applying the XML Schema `whiteSpace="collapse"`
+ * normalization step.  It returns the normalized string without any further
+ * canonicalization.
+ *
+ * @param value A candidate `xsd:decimal` lexical form.
+ * @returns The normalized string branded as {@link Decimal}.
+ * @throws {TypeError} Thrown when the value is not a valid `xsd:decimal`
+ *                     lexical form.
+ * @example
+ * ```typescript
+ * const price = parseDecimal("12.50");
+ * ```
+ * @example
+ * ```typescript
+ * const price = parseDecimal(" 12.50 ");
+ * console.assert(price === "12.50");
+ * ```
+ * @example
+ * ```typescript
+ * try {
+ *   parseDecimal("1e3");
+ * } catch (error) {
+ *   console.assert(error instanceof TypeError);
+ * }
+ * ```
+ * @since 2.1.0
+ */
+export function parseDecimal(value: string): Decimal {
+  const normalized = collapseXmlSchemaWhitespace(value);
+  if (!isDecimal(normalized)) {
+    throw new TypeError(
+      `${JSON.stringify(value)} is not a valid xsd:decimal lexical form.`,
+    );
+  }
+  return normalized as Decimal;
+}

package/src/internal/multicodec.test.ts

@@ -0,0 +1,68 @@
+import { deepStrictEqual, throws } from "node:assert";
+import { test } from "node:test";
+import {
+  addMulticodecPrefix,
+  getMulticodecPrefix,
+  removeMulticodecPrefix,
+} from "./multicodec.ts";
+
+test("getMulticodecPrefix() decodes supported multicodec prefixes", () => {
+  deepStrictEqual(
+    getMulticodecPrefix(Uint8Array.from([0xed, 0x01, 0xaa])),
+    { code: 0xed, prefixLength: 2 },
+  );
+  deepStrictEqual(
+    getMulticodecPrefix(Uint8Array.from([0x85, 0x24, 0xaa])),
+    { code: 0x1205, prefixLength: 2 },
+  );
+});
+
+test("removeMulticodecPrefix() strips the varint prefix", () => {
+  deepStrictEqual(
+    removeMulticodecPrefix(Uint8Array.from([0xed, 0x01, 0x11, 0x22])),
+    Uint8Array.from([0x11, 0x22]),
+  );
+});
+
+test("addMulticodecPrefix() prepends the varint-encoded code", () => {
+  deepStrictEqual(
+    addMulticodecPrefix(0xed, Uint8Array.from([0x11, 0x22])),
+    Uint8Array.from([0xed, 0x01, 0x11, 0x22]),
+  );
+  deepStrictEqual(
+    addMulticodecPrefix(0x1205, Uint8Array.from([0x11, 0x22])),
+    Uint8Array.from([0x85, 0x24, 0x11, 0x22]),
+  );
+});
+
+test("multicodec helpers round-trip prefixed payloads", () => {
+  const payload = Uint8Array.from([0xde, 0xad, 0xbe, 0xef]);
+  const prefixed = addMulticodecPrefix(0x1205, payload);
+  deepStrictEqual(getMulticodecPrefix(prefixed), {
+    code: 0x1205,
+    prefixLength: 2,
+  });
+  deepStrictEqual(removeMulticodecPrefix(prefixed), payload);
+});
+
+test("multicodec helpers reject malformed prefixes", () => {
+  throws(
+    () => getMulticodecPrefix(new Uint8Array([])),
+    new TypeError("Invalid multicodec prefix."),
+  );
+  throws(
+    () => getMulticodecPrefix(Uint8Array.from([0x80])),
+    new TypeError("Invalid multicodec prefix."),
+  );
+  throws(
+    () =>
+      getMulticodecPrefix(
+        Uint8Array.from([0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80]),
+      ),
+    new TypeError("Invalid multicodec prefix."),
+  );
+  throws(
+    () => addMulticodecPrefix(-1, Uint8Array.from([0x00])),
+    new TypeError("Invalid multicodec code."),
+  );
+});

package/src/internal/multicodec.ts

@@ -0,0 +1,53 @@
+const INVALID_MULTICODEC_PREFIX = "Invalid multicodec prefix.";
+
+export interface MulticodecPrefix {
+  code: number;
+  prefixLength: number;
+}
+
+export function getMulticodecPrefix(
+  data: Uint8Array,
+): MulticodecPrefix {
+  if (data.length < 1) throw new TypeError(INVALID_MULTICODEC_PREFIX);
+  let code = 0;
+  let shift = 0;
+  for (let i = 0; i < data.length; i++) {
+    const byte = data[i];
+    code += (byte & 0x7f) * 2 ** shift;
+    if (code > Number.MAX_SAFE_INTEGER) {
+      throw new TypeError(INVALID_MULTICODEC_PREFIX);
+    }
+    if ((byte & 0x80) === 0) {
+      return { code, prefixLength: i + 1 };
+    }
+    shift += 7;
+    if (shift >= 53) throw new TypeError(INVALID_MULTICODEC_PREFIX);
+  }
+  throw new TypeError(INVALID_MULTICODEC_PREFIX);
+}
+
+export function removeMulticodecPrefix(data: Uint8Array): Uint8Array {
+  const { prefixLength } = getMulticodecPrefix(data);
+  return data.slice(prefixLength);
+}
+
+export function addMulticodecPrefix(
+  code: number,
+  payload: Uint8Array,
+): Uint8Array {
+  if (!Number.isSafeInteger(code) || code < 0) {
+    throw new TypeError("Invalid multicodec code.");
+  }
+  const prefix: number[] = [];
+  let value = code;
+  do {
+    let byte = value & 0x7f;
+    value = Math.floor(value / 0x80);
+    if (value > 0) byte |= 0x80;
+    prefix.push(byte);
+  } while (value > 0);
+  const prefixed = new Uint8Array(prefix.length + payload.length);
+  prefixed.set(prefix);
+  prefixed.set(payload, prefix.length);
+  return prefixed;
+}

package/src/jsonld.ts

@@ -0,0 +1,4 @@
+// @ts-ignore TS7016
+import jsonld from "jsonld/dist/jsonld.esm.js";
+
+export default jsonld as typeof import("jsonld");

package/src/key.test.ts

@@ -1,4 +1,4 @@
-import { deepStrictEqual } from "node:assert";
+import { deepStrictEqual, rejects } from "node:assert";
 import { test } from "node:test";
 import { exportJwk, importJwk } from "./jwk.ts";
 import {
@@ -9,6 +9,7 @@ import {
   importPkcs1,
   importSpki,
 } from "./key.ts";
+import { encodeMultibase } from "./multibase/mod.ts";
 
 // cSpell: disable
 const rsaSpki = "-----BEGIN PUBLIC KEY-----\n" +
@@ -122,6 +123,26 @@ test("importMultibase()", async () => {
   deepStrictEqual(await exportJwk(ed25519Key), ed25519Jwk);
 });
 
+test("importMultibase() rejects malformed multicodec prefixes", async () => {
+  const decoder = new TextDecoder();
+  await rejects(
+    () =>
+      importMultibaseKey(
+        decoder.decode(encodeMultibase("base58btc", new Uint8Array([]))),
+      ),
+    new TypeError("Invalid multicodec prefix."),
+  );
+  await rejects(
+    () =>
+      importMultibaseKey(
+        decoder.decode(
+          encodeMultibase("base58btc", Uint8Array.from([0x80])),
+        ),
+      ),
+    new TypeError("Invalid multicodec prefix."),
+  );
+});
+
 test("exportMultibaseKey()", async () => {
   const rsaKey = await importJwk(rsaJwk, "public");
   const rsaMb = await exportMultibaseKey(rsaKey);

package/src/key.ts

@@ -1,10 +1,13 @@
 import { Integer, Sequence } from "asn1js";
 import { decodeBase64, encodeBase64 } from "byte-encodings/base64";
 import { decodeBase64Url } from "byte-encodings/base64url";
-import { decodeHex } from "byte-encodings/hex";
-import { addPrefix, getCodeFromData, rmPrefix } from "multicodec";
 import { createPublicKey } from "node:crypto";
 import { PublicKeyInfo } from "pkijs";
+import {
+  addMulticodecPrefix,
+  getMulticodecPrefix,
+  removeMulticodecPrefix,
+} from "./internal/multicodec.ts";
 import { validateCryptoKey } from "./jwk.ts";
 import { decodeMultibase, encodeMultibase } from "./multibase/mod.ts";
 
@@ -101,8 +104,8 @@ export function importPem(pem: string): Promise<CryptoKey> {
  */
 export async function importMultibaseKey(key: string): Promise<CryptoKey> {
   const decoded = decodeMultibase(key);
-  const code: number = getCodeFromData(decoded);
-  const content = rmPrefix(decoded);
+  const { code } = getMulticodecPrefix(decoded);
+  const content = removeMulticodecPrefix(decoded);
   if (code === 0x1205) { // rsa-pub
     const keyObject = createPublicKey({
       // deno-lint-ignore no-explicit-any
@@ -177,11 +180,9 @@ export async function exportMultibaseKey(key: CryptoKey): Promise<string> {
       "Unsupported key type: " + JSON.stringify(key.algorithm),
     );
   }
-  const codeHex = code.toString(16);
-  const codeBytes = decodeHex(codeHex.length % 2 < 1 ? codeHex : "0" + codeHex);
-  const prefixed = addPrefix(codeBytes, new Uint8Array(content));
+  const prefixed = addMulticodecPrefix(code, new Uint8Array(content));
   const encoded = encodeMultibase("base58btc", prefixed);
   return new TextDecoder().decode(encoded);
 }
 
-// cSpell: ignore multicodec pkijs
+// cSpell: ignore pkijs

package/src/mod.ts

@@ -24,6 +24,12 @@ export {
   importPkcs1,
   importSpki,
 } from "./key.ts";
+export {
+  canParseDecimal,
+  type Decimal,
+  isDecimal,
+  parseDecimal,
+} from "./decimal.ts";
 export { LanguageString } from "./langstr.ts";
 export {
   decodeMultibase,

package/tsdown.config.ts

@@ -4,7 +4,7 @@ import { defineConfig } from "tsdown";
 
 export default [
   defineConfig({
-    entry: ["src/mod.ts"],
+    entry: ["src/mod.ts", "src/jsonld.ts"],
     dts: { compilerOptions: { isolatedDeclarations: true, declaration: true } },
     format: ["esm", "cjs"],
     platform: "neutral",