@typed-web/form-utils 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Łukasz Jagodziński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @typed-web/form-utils
+
+Utilities for form handling: path conversion, object flattening, and array diffing.
+
+## Installation
+
+```bash
+npm install @typed-web/form-utils
+```
+
+## Exports
+
+### Object Conversion
+- `flatObjectToNestedObject` - Convert flat objects to nested structures
+- `nestedObjectToFlatObject` - Convert nested objects to flat structures
+
+### Path Utilities
+- `setValueAtPath` - Set value at path in object
+- `stringPathToArrayPath` - Convert string path to array
+- `arrayPathToStringPath` - Convert array path to string
+
+### Array Utilities
+- `getArraysDiff` - Compute differences between arrays
+
+### Types
+- `FlatObject`, `NestedObject`, `GetArraysDiffArgs`
+
+## Usage
+
+```typescript
+import {
+  flatObjectToNestedObject,
+  stringPathToArrayPath,
+  setValueAtPath,
+} from "@typed-web/form-utils";
+
+// Convert flat to nested
+const nested = flatObjectToNestedObject({
+  "user.name": "John",
+  "addresses[0].city": "NYC",
+});
+// { user: { name: "John" }, addresses: [{ city: "NYC" }] }
+
+// Parse path
+const path = stringPathToArrayPath("user.addresses[0].city");
+// ["user", "addresses", 0, "city"]
+
+// Set value at path
+const obj = {};
+setValueAtPath(obj, ["user", "name"], "John");
+// { user: { name: "John" } }
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { FlatObject, NestedObject } from "./lib/types.ts";
+export { setValueAtPath } from "./lib/set-value-at-path.ts";
+export { stringPathToArrayPath } from "./lib/string-path-to-array-path.ts";
+export { arrayPathToStringPath } from "./lib/array-path-to-string-path.ts";
+export { flatObjectToNestedObject } from "./lib/flat-object-to-nested-object.ts";
+export { nestedObjectToFlatObject } from "./lib/nested-object-to-flat-object.ts";
+export { getArraysDiff } from "./lib/get-arrays-diff.ts";
+export type { GetArraysDiffArgs } from "./lib/get-arrays-diff.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG/D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAG3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAGjF,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,142 @@
+// src/lib/string-path-to-array-path.ts
+var BRACKET_NOTATION_REGEX = /^\[(.+?)\](.*)$/;
+var DOT_NOTATION_REGEX = /^\.?([^\.\[\]]+)(.*)$/;
+var NUMERIC_KEY_REGEX = /^\d+$/;
+function parsePath(currentPath) {
+  if (currentPath.length === 0) {
+    return [];
+  }
+  const bracketMatch = currentPath.match(BRACKET_NOTATION_REGEX);
+  const dotMatch = currentPath.match(DOT_NOTATION_REGEX);
+  if (bracketMatch) {
+    const [, key = "", rest = ""] = bracketMatch;
+    const parsedKey = NUMERIC_KEY_REGEX.test(key) ? Number(key) : key;
+    const restResult = parsePath(rest);
+    if (restResult === null) {
+      return null;
+    }
+    return [parsedKey, ...restResult];
+  } else if (dotMatch) {
+    const [, key = "", rest = ""] = dotMatch;
+    const parsedKey = NUMERIC_KEY_REGEX.test(key) ? Number(key) : key;
+    const restResult = parsePath(rest);
+    if (restResult === null) {
+      return null;
+    }
+    return [parsedKey, ...restResult];
+  }
+  return null;
+}
+function stringPathToArrayPath(path) {
+  if (path.length === 0) {
+    return [];
+  }
+  const result = parsePath(path);
+  if (result === null) {
+    return [path];
+  }
+  return result;
+}
+
+// src/lib/set-value-at-path.ts
+function setValueAtPath(object, path, value) {
+  const pathSegments = stringPathToArrayPath(path);
+  if (pathSegments.length === 0) {
+    throw new Error("Cannot set value on empty path");
+  }
+  const leadingSegments = pathSegments.slice(0, -1);
+  const lastSegment = pathSegments[pathSegments.length - 1];
+  if (lastSegment === void 0) {
+    throw new Error("Invalid path: last segment is undefined");
+  }
+  let currentObject = object;
+  for (let i = 0; i < leadingSegments.length; i++) {
+    const currentSegment = leadingSegments[i];
+    if (currentSegment === void 0) {
+      throw new Error(`Invalid path: segment at index ${i} is undefined`);
+    }
+    if (!(currentSegment in currentObject)) {
+      const nextSegment = leadingSegments[i + 1] ?? lastSegment;
+      currentObject[currentSegment] = typeof nextSegment === "number" ? [] : {};
+    }
+    const nextValue = currentObject[currentSegment];
+    if (typeof nextValue !== "object" || nextValue === null) {
+      throw new Error(
+        `Cannot navigate through path: expected object at segment "${currentSegment}", got ${typeof nextValue}`
+      );
+    }
+    currentObject = nextValue;
+  }
+  currentObject[lastSegment] = value;
+  return object;
+}
+
+// src/lib/array-path-to-string-path.ts
+function arrayPathToStringPath(path) {
+  return path.reduce((str, item) => {
+    if (typeof item === "symbol") {
+      return str + (str === "" ? "" : ".") + item.toString();
+    }
+    if (typeof item === "number" || !Number.isNaN(Number(item))) {
+      return str + "[" + item + "]";
+    }
+    return str + (str === "" ? "" : ".") + item;
+  }, "");
+}
+
+// src/lib/flat-object-to-nested-object.ts
+function flatObjectToNestedObject(flatStructure) {
+  const result = {};
+  for (const [path, value] of Object.entries(flatStructure)) {
+    setValueAtPath(result, path, value);
+  }
+  return result;
+}
+
+// src/lib/nested-object-to-flat-object.ts
+function nestedObjectToFlatObject(nestedStructure) {
+  const result = {};
+  function walk(obj, currentPath) {
+    if (typeof obj !== "object" || obj === null) {
+      result[currentPath] = obj;
+      return;
+    }
+    if (Array.isArray(obj)) {
+      obj.forEach((item, index) => {
+        const newPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;
+        walk(item, newPath);
+      });
+    } else {
+      for (const [key, value] of Object.entries(obj)) {
+        const newPath = currentPath ? `${currentPath}.${key}` : key;
+        walk(value, newPath);
+      }
+    }
+  }
+  walk(nestedStructure, "");
+  return result;
+}
+
+// src/lib/get-arrays-diff.ts
+function getArraysDiff(args) {
+  const { before, after, key, equals } = args;
+  const isEqual = equals;
+  const beforeMap = new Map(before.map((b) => [key(b), b]));
+  const afterMap = new Map(after.map((a) => [key(a), a]));
+  const added = after.filter((a) => !beforeMap.has(key(a)));
+  const removed = before.filter((b) => !afterMap.has(key(b)));
+  const modified = after.map((a) => {
+    const b = beforeMap.get(key(a));
+    return b !== void 0 && !isEqual(b, a) ? { before: b, after: a } : void 0;
+  }).filter((x) => x !== void 0);
+  return { added, removed, modified };
+}
+export {
+  arrayPathToStringPath,
+  flatObjectToNestedObject,
+  getArraysDiff,
+  nestedObjectToFlatObject,
+  setValueAtPath,
+  stringPathToArrayPath
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/string-path-to-array-path.ts", "../src/lib/set-value-at-path.ts", "../src/lib/array-path-to-string-path.ts", "../src/lib/flat-object-to-nested-object.ts", "../src/lib/nested-object-to-flat-object.ts", "../src/lib/get-arrays-diff.ts"],
+  "sourcesContent": ["// Regular expression to match bracket notation: [key] followed by rest of path.\nconst BRACKET_NOTATION_REGEX = /^\\[(.+?)\\](.*)$/;\n\n// Regular expression to match dot notation: optional dot followed by property\n// name and rest of path.\nconst DOT_NOTATION_REGEX = /^\\.?([^\\.\\[\\]]+)(.*)$/;\n\n// Regular expression to test if a string contains only digits\n// (for array indices).\nconst NUMERIC_KEY_REGEX = /^\\d+$/;\n\n/**\n * Internal recursive parser for path segments.\n * Returns null if the path contains invalid syntax that cannot be parsed.\n *\n * @param currentPath - The remaining path to parse\n * @returns Array of path segments, or null if parsing fails\n */\nfunction parsePath(currentPath: string): Array<string | number> | null {\n  // Base case: empty path\n  if (currentPath.length === 0) {\n    return [];\n  }\n\n  // Try to match bracket notation first, then dot notation.\n  const bracketMatch = currentPath.match(BRACKET_NOTATION_REGEX);\n  const dotMatch = currentPath.match(DOT_NOTATION_REGEX);\n\n  if (bracketMatch) {\n    const [, key = \"\", rest = \"\"] = bracketMatch;\n    // Convert numeric keys to numbers, keep string keys as strings.\n    const parsedKey = NUMERIC_KEY_REGEX.test(key) ? Number(key) : key;\n\n    // Recursively process the rest of the path.\n    const restResult = parsePath(rest);\n\n    // If rest parsing failed (returned null), propagate failure\n    if (restResult === null) {\n      return null;\n    }\n\n    return [parsedKey, ...restResult];\n  } else if (dotMatch) {\n    const [, key = \"\", rest = \"\"] = dotMatch;\n    // Convert numeric keys to numbers, keep string keys as strings.\n    const parsedKey = NUMERIC_KEY_REGEX.test(key) ? Number(key) : key;\n\n    // Recursively process the rest of the path.\n    const restResult = parsePath(rest);\n\n    // If rest parsing failed (returned null), propagate failure\n    if (restResult === null) {\n      return null;\n    }\n\n    return [parsedKey, ...restResult];\n  }\n\n  // No pattern matched but we still have content - invalid path\n  // Return null to signal failure\n  return null;\n}\n\n/**\n * Converts a string path to an array of path segments.\n * Supports both bracket notation (e.g., \"[0]\", \"[key]\") and dot notation (e.g., \".prop\", \"prop\").\n * All numeric strings are converted to numbers regardless of notation type.\n * If the path contains invalid syntax, returns the entire path as a single segment.\n *\n * @param path - The string path to convert (e.g., \"user.profile[0].name\")\n * @returns Array of path segments where numeric strings become numbers\n *\n * @example\n * stringPathToArrayPath(\"user.profile[0].name\") // [\"user\", \"profile\", 0, \"name\"]\n * stringPathToArrayPath(\"users.0[name]\") // [\"users\", 0, \"name\"]\n * stringPathToArrayPath(\"[0].title\") // [0, \"title\"]\n * stringPathToArrayPath(\"\") // []\n * stringPathToArrayPath(\"invalid[[path\") // [\"invalid[[path\"] (invalid syntax)\n */\nexport function stringPathToArrayPath(path: string): Array<string | number> {\n  // Handle empty path.\n  if (path.length === 0) {\n    return [];\n  }\n\n  // Attempt to parse the path\n  const result = parsePath(path);\n\n  // If parsing failed, return the entire path as a single segment\n  if (result === null) {\n    return [path];\n  }\n\n  return result;\n}\n", "import { stringPathToArrayPath } from \"./string-path-to-array-path.ts\";\n\n/**\n * Sets a value at a specific path within an object, creating nested objects/arrays as needed.\n * The path is parsed using dot notation and bracket notation to navigate through the object structure.\n * Missing intermediate objects are automatically created as objects or arrays based on the next segment type.\n *\n * @param object - The target object to modify (will be mutated)\n * @param path - The path string indicating where to set the value (e.g., \"user.profile[0].name\")\n * @param value - The value to set at the specified path\n * @returns The modified input object (same reference, mutated)\n *\n * @example\n * const obj = {};\n * setValueAtPath(obj, \"user.profile.name\", \"John\");\n * // obj becomes { user: { profile: { name: \"John\" } } }\n *\n * @example\n * const obj = {};\n * setValueAtPath(obj, \"users[0].name\", \"Alice\");\n * // obj becomes { users: [{ name: \"Alice\" }] }\n *\n * @example\n * const obj = {};\n * setValueAtPath(obj, \"config[database][host]\", \"localhost\");\n * // obj becomes { config: { database: { host: \"localhost\" } } }\n */\nexport function setValueAtPath<T extends Record<string | number, unknown>>(\n  object: T,\n  path: string,\n  value: unknown,\n): T {\n  const pathSegments = stringPathToArrayPath(path);\n\n  // Handle empty path - cannot set value on empty path.\n  if (pathSegments.length === 0) {\n    throw new Error(\"Cannot set value on empty path\");\n  }\n\n  // Extract leading segments (all but last) and the final segment.\n  const leadingSegments = pathSegments.slice(0, -1);\n  const lastSegment = pathSegments[pathSegments.length - 1];\n\n  // Type guard for lastSegment.\n  if (lastSegment === undefined) {\n    throw new Error(\"Invalid path: last segment is undefined\");\n  }\n\n  // Navigate through the object, creating intermediate objects/arrays as needed.\n  let currentObject: Record<string | number, unknown> = object;\n\n  for (let i = 0; i < leadingSegments.length; i++) {\n    const currentSegment = leadingSegments[i];\n\n    // Type guard for currentSegment.\n    if (currentSegment === undefined) {\n      throw new Error(`Invalid path: segment at index ${i} is undefined`);\n    }\n\n    // If the current property doesn't exist, create it.\n    if (!(currentSegment in currentObject)) {\n      // Determine the next segment to decide whether to create an object or array.\n      const nextSegment = leadingSegments[i + 1] ?? lastSegment;\n      // Create array if next segment is a number, otherwise create object.\n      currentObject[currentSegment] = typeof nextSegment === \"number\" ? [] : {};\n    }\n\n    // Move deeper into the structure.\n    const nextValue = currentObject[currentSegment];\n\n    // Type guard to ensure we have an object-like structure to navigate into.\n    if (typeof nextValue !== \"object\" || nextValue === null) {\n      throw new Error(\n        `Cannot navigate through path: expected object at segment \"${currentSegment}\", got ${typeof nextValue}`,\n      );\n    }\n\n    currentObject = nextValue as Record<string | number, unknown>;\n  }\n\n  // Set the final value.\n  currentObject[lastSegment] = value;\n\n  return object;\n}\n", "/**\n * Convert array path to string format.\n * Examples: [\"user\", \"name\"] -> \"user.name\", [\"items\", 0] -> \"items[0]\"\n *\n * @param path - Array of path segments (strings, numbers, or symbols)\n * @returns String path with dot notation for object properties and bracket notation for array indices\n *\n * @example\n * arrayPathToStringPath([\"user\", \"name\"]) // \"user.name\"\n * arrayPathToStringPath([\"items\", 0]) // \"items[0]\"\n * arrayPathToStringPath([\"addresses\", 0, \"city\"]) // \"addresses[0].city\"\n * arrayPathToStringPath([]) // \"\"\n */\nexport function arrayPathToStringPath(path: Array<PropertyKey>): string {\n  return path.reduce((str: string, item) => {\n    if (typeof item === \"symbol\") {\n      return str + (str === \"\" ? \"\" : \".\") + item.toString();\n    }\n    if (typeof item === \"number\" || !Number.isNaN(Number(item))) {\n      return str + \"[\" + item + \"]\";\n    }\n    return str + (str === \"\" ? \"\" : \".\") + item;\n  }, \"\");\n}\n", "import { setValueAtPath } from \"./set-value-at-path.ts\";\nimport type { FlatObject, NestedObject } from \"./types.ts\";\n\n/**\n * Converts a flat structure object to a nested structure object.\n * Uses path strings like \"user.name\" or \"addresses[0].city\" to create nested structure.\n *\n * @param flatStructure - Flat structure object with string paths as keys\n * @returns Nested structure object with hierarchical structure\n *\n * @example\n * const flat = {\n *   \"user.name\": \"John\",\n *   \"addresses[0].city\": \"San Francisco\"\n * };\n * const nested = flatObjectToNestedObject(flat);\n * // {\n * //   user: { name: \"John\" },\n * //   addresses: [{ city: \"San Francisco\" }]\n * // }\n */\nexport function flatObjectToNestedObject<T = unknown, V = unknown>(\n  flatStructure: FlatObject<V>,\n): NestedObject<T> {\n  const result = {} as Record<string | number, unknown>;\n\n  for (const [path, value] of Object.entries(flatStructure)) {\n    setValueAtPath(result, path, value);\n  }\n\n  return result as NestedObject<T>;\n}\n", "import type { FlatObject, NestedObject } from \"./types.ts\";\n\n/**\n * Converts a nested structure object to a flat structure object.\n * Recursively walks the nested structure and creates path strings.\n *\n * @param nestedStructure - Nested structure object with hierarchical structure\n * @returns Flat structure object with string paths as keys\n *\n * @example\n * const nested = {\n *   user: { name: \"John\" },\n *   addresses: [{ city: \"San Francisco\" }]\n * };\n * const flat = nestedObjectToFlatObject(nested);\n * // {\n * //   \"user.name\": \"John\",\n * //   \"addresses[0].city\": \"San Francisco\"\n * // }\n */\nexport function nestedObjectToFlatObject<T = unknown, V = unknown>(\n  nestedStructure: NestedObject<T>,\n): FlatObject<V> {\n  const result: FlatObject<V> = {};\n\n  function walk(obj: unknown, currentPath: string) {\n    if (typeof obj !== \"object\" || obj === null) {\n      // Leaf node - this is a value\n      result[currentPath] = obj as V;\n      return;\n    }\n\n    if (Array.isArray(obj)) {\n      // Handle arrays\n      obj.forEach((item, index) => {\n        const newPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;\n        walk(item, newPath);\n      });\n    } else {\n      // Handle objects\n      for (const [key, value] of Object.entries(obj)) {\n        const newPath = currentPath ? `${currentPath}.${key}` : key;\n        walk(value, newPath);\n      }\n    }\n  }\n\n  walk(nestedStructure, \"\");\n\n  return result;\n}\n", "export interface GetArraysDiffArgs<T extends Record<string, unknown>> {\n  before: Array<T>;\n  after: Array<T>;\n  key: (item: T) => PropertyKey;\n  equals: (a: T, b: T) => boolean;\n}\n\nexport function getArraysDiff<T extends Record<string, unknown>>(\n  args: GetArraysDiffArgs<T>,\n): {\n  added: Array<T>;\n  removed: Array<T>;\n  modified: Array<{ before: T; after: T }>;\n} {\n  const { before, after, key, equals } = args;\n  const isEqual = equals;\n\n  // Build lookup maps/sets for efficient comparisons by key.\n  const beforeMap = new Map(before.map((b) => [key(b), b]));\n  const afterMap = new Map(after.map((a) => [key(a), a]));\n\n  const added = after.filter((a) => !beforeMap.has(key(a)));\n  const removed = before.filter((b) => !afterMap.has(key(b)));\n\n  const modified = after\n    .map((a): { before: T; after: T } | undefined => {\n      const b = beforeMap.get(key(a));\n      return b !== undefined && !isEqual(b, a) ? { before: b, after: a } : undefined;\n    })\n    .filter((x): x is { before: T; after: T } => x !== undefined);\n\n  return { added, removed, modified };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/array-path-to-string-path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Convert array path to string format.
+ * Examples: ["user", "name"] -> "user.name", ["items", 0] -> "items[0]"
+ *
+ * @param path - Array of path segments (strings, numbers, or symbols)
+ * @returns String path with dot notation for object properties and bracket notation for array indices
+ *
+ * @example
+ * arrayPathToStringPath(["user", "name"]) // "user.name"
+ * arrayPathToStringPath(["items", 0]) // "items[0]"
+ * arrayPathToStringPath(["addresses", 0, "city"]) // "addresses[0].city"
+ * arrayPathToStringPath([]) // ""
+ */
+export declare function arrayPathToStringPath(path: Array<PropertyKey>): string;
+//# sourceMappingURL=array-path-to-string-path.d.ts.map

package/dist/lib/array-path-to-string-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-path-to-string-path.d.ts","sourceRoot":"","sources":["../../src/lib/array-path-to-string-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,MAAM,CAUtE"}

package/dist/lib/flat-object-to-nested-object.d.ts

@@ -0,0 +1,21 @@
+import type { FlatObject, NestedObject } from "./types.ts";
+/**
+ * Converts a flat structure object to a nested structure object.
+ * Uses path strings like "user.name" or "addresses[0].city" to create nested structure.
+ *
+ * @param flatStructure - Flat structure object with string paths as keys
+ * @returns Nested structure object with hierarchical structure
+ *
+ * @example
+ * const flat = {
+ *   "user.name": "John",
+ *   "addresses[0].city": "San Francisco"
+ * };
+ * const nested = flatObjectToNestedObject(flat);
+ * // {
+ * //   user: { name: "John" },
+ * //   addresses: [{ city: "San Francisco" }]
+ * // }
+ */
+export declare function flatObjectToNestedObject<T = unknown, V = unknown>(flatStructure: FlatObject<V>): NestedObject<T>;
+//# sourceMappingURL=flat-object-to-nested-object.d.ts.map

package/dist/lib/flat-object-to-nested-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-object-to-nested-object.d.ts","sourceRoot":"","sources":["../../src/lib/flat-object-to-nested-object.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC/D,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC,GAC3B,YAAY,CAAC,CAAC,CAAC,CAQjB"}

package/dist/lib/get-arrays-diff.d.ts

@@ -0,0 +1,15 @@
+export interface GetArraysDiffArgs<T extends Record<string, unknown>> {
+    before: Array<T>;
+    after: Array<T>;
+    key: (item: T) => PropertyKey;
+    equals: (a: T, b: T) => boolean;
+}
+export declare function getArraysDiff<T extends Record<string, unknown>>(args: GetArraysDiffArgs<T>): {
+    added: Array<T>;
+    removed: Array<T>;
+    modified: Array<{
+        before: T;
+        after: T;
+    }>;
+};
+//# sourceMappingURL=get-arrays-diff.d.ts.map

package/dist/lib/get-arrays-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-arrays-diff.d.ts","sourceRoot":"","sources":["../../src/lib/get-arrays-diff.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAChB,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,WAAW,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;CACjC;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACzB;IACD,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAC1C,CAmBA"}

package/dist/lib/nested-object-to-flat-object.d.ts

@@ -0,0 +1,21 @@
+import type { FlatObject, NestedObject } from "./types.ts";
+/**
+ * Converts a nested structure object to a flat structure object.
+ * Recursively walks the nested structure and creates path strings.
+ *
+ * @param nestedStructure - Nested structure object with hierarchical structure
+ * @returns Flat structure object with string paths as keys
+ *
+ * @example
+ * const nested = {
+ *   user: { name: "John" },
+ *   addresses: [{ city: "San Francisco" }]
+ * };
+ * const flat = nestedObjectToFlatObject(nested);
+ * // {
+ * //   "user.name": "John",
+ * //   "addresses[0].city": "San Francisco"
+ * // }
+ */
+export declare function nestedObjectToFlatObject<T = unknown, V = unknown>(nestedStructure: NestedObject<T>): FlatObject<V>;
+//# sourceMappingURL=nested-object-to-flat-object.d.ts.map

package/dist/lib/nested-object-to-flat-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-object-to-flat-object.d.ts","sourceRoot":"","sources":["../../src/lib/nested-object-to-flat-object.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC/D,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAC/B,UAAU,CAAC,CAAC,CAAC,CA4Bf"}

package/dist/lib/set-value-at-path.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sets a value at a specific path within an object, creating nested objects/arrays as needed.
+ * The path is parsed using dot notation and bracket notation to navigate through the object structure.
+ * Missing intermediate objects are automatically created as objects or arrays based on the next segment type.
+ *
+ * @param object - The target object to modify (will be mutated)
+ * @param path - The path string indicating where to set the value (e.g., "user.profile[0].name")
+ * @param value - The value to set at the specified path
+ * @returns The modified input object (same reference, mutated)
+ *
+ * @example
+ * const obj = {};
+ * setValueAtPath(obj, "user.profile.name", "John");
+ * // obj becomes { user: { profile: { name: "John" } } }
+ *
+ * @example
+ * const obj = {};
+ * setValueAtPath(obj, "users[0].name", "Alice");
+ * // obj becomes { users: [{ name: "Alice" }] }
+ *
+ * @example
+ * const obj = {};
+ * setValueAtPath(obj, "config[database][host]", "localhost");
+ * // obj becomes { config: { database: { host: "localhost" } } }
+ */
+export declare function setValueAtPath<T extends Record<string | number, unknown>>(object: T, path: string, value: unknown): T;
+//# sourceMappingURL=set-value-at-path.d.ts.map

package/dist/lib/set-value-at-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-value-at-path.d.ts","sourceRoot":"","sources":["../../src/lib/set-value-at-path.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EACvE,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,CAAC,CAqDH"}

package/dist/lib/string-path-to-array-path.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts a string path to an array of path segments.
+ * Supports both bracket notation (e.g., "[0]", "[key]") and dot notation (e.g., ".prop", "prop").
+ * All numeric strings are converted to numbers regardless of notation type.
+ * If the path contains invalid syntax, returns the entire path as a single segment.
+ *
+ * @param path - The string path to convert (e.g., "user.profile[0].name")
+ * @returns Array of path segments where numeric strings become numbers
+ *
+ * @example
+ * stringPathToArrayPath("user.profile[0].name") // ["user", "profile", 0, "name"]
+ * stringPathToArrayPath("users.0[name]") // ["users", 0, "name"]
+ * stringPathToArrayPath("[0].title") // [0, "title"]
+ * stringPathToArrayPath("") // []
+ * stringPathToArrayPath("invalid[[path") // ["invalid[[path"] (invalid syntax)
+ */
+export declare function stringPathToArrayPath(path: string): Array<string | number>;
+//# sourceMappingURL=string-path-to-array-path.d.ts.map

package/dist/lib/string-path-to-array-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-path-to-array-path.d.ts","sourceRoot":"","sources":["../../src/lib/string-path-to-array-path.ts"],"names":[],"mappings":"AA+DA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAe1E"}

package/dist/lib/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Flat structure format - values mapped by string paths
+ * @example
+ * {
+ *   "user.name": "John",
+ *   "addresses[0].city": "San Francisco",
+ *   "addresses[0].state": "California"
+ * }
+ */
+export type FlatObject<V = unknown> = Record<string, V>;
+/**
+ * Nested structure format - values in a nested object structure
+ * @example
+ * {
+ *   user: { name: "John" },
+ *   addresses: [
+ *     { city: "San Francisco", state: "California" }
+ *   ]
+ * }
+ */
+export type NestedObject<T = unknown> = T extends object ? {
+    [K in keyof T]?: T[K] extends object ? NestedObject<T[K]> : unknown;
+} : unknown;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,SAAS,MAAM,GACpD;KACG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO;CACpE,GACD,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@typed-web/form-utils",
+  "version": "0.1.1",
+  "description": "Shared utilities for form handling: path parsing, error conversion, and array diffing",
+  "author": "Łukasz Jagodziński <luke.jagodzinski@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typed-web/typed-web.git",
+    "directory": "packages/form-utils"
+  },
+  "homepage": "https://github.com/typed-web/typed-web/tree/main/packages/form-utils#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "esbuild": "^0.27.2"
+  },
+  "keywords": [
+    "form",
+    "utilities",
+    "path-parsing",
+    "error-conversion",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:types && pnpm run build:esm",
+    "build:esm": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --platform=neutral --sourcemap",
+    "build:types": "tsc --project tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "test": "node --disable-warning=ExperimentalWarning --test './src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// Types
+export type { FlatObject, NestedObject } from "./lib/types.ts";
+
+// Path utilities
+export { setValueAtPath } from "./lib/set-value-at-path.ts";
+export { stringPathToArrayPath } from "./lib/string-path-to-array-path.ts";
+export { arrayPathToStringPath } from "./lib/array-path-to-string-path.ts";
+
+// Structure conversion
+export { flatObjectToNestedObject } from "./lib/flat-object-to-nested-object.ts";
+export { nestedObjectToFlatObject } from "./lib/nested-object-to-flat-object.ts";
+
+// Array utilities
+export { getArraysDiff } from "./lib/get-arrays-diff.ts";
+export type { GetArraysDiffArgs } from "./lib/get-arrays-diff.ts";

package/src/lib/array-path-to-string-path.ts

@@ -0,0 +1,24 @@
+/**
+ * Convert array path to string format.
+ * Examples: ["user", "name"] -> "user.name", ["items", 0] -> "items[0]"
+ *
+ * @param path - Array of path segments (strings, numbers, or symbols)
+ * @returns String path with dot notation for object properties and bracket notation for array indices
+ *
+ * @example
+ * arrayPathToStringPath(["user", "name"]) // "user.name"
+ * arrayPathToStringPath(["items", 0]) // "items[0]"
+ * arrayPathToStringPath(["addresses", 0, "city"]) // "addresses[0].city"
+ * arrayPathToStringPath([]) // ""
+ */
+export function arrayPathToStringPath(path: Array<PropertyKey>): string {
+  return path.reduce((str: string, item) => {
+    if (typeof item === "symbol") {
+      return str + (str === "" ? "" : ".") + item.toString();
+    }
+    if (typeof item === "number" || !Number.isNaN(Number(item))) {
+      return str + "[" + item + "]";
+    }
+    return str + (str === "" ? "" : ".") + item;
+  }, "");
+}

package/src/lib/flat-object-to-nested-object.ts

@@ -0,0 +1,32 @@
+import { setValueAtPath } from "./set-value-at-path.ts";
+import type { FlatObject, NestedObject } from "./types.ts";
+
+/**
+ * Converts a flat structure object to a nested structure object.
+ * Uses path strings like "user.name" or "addresses[0].city" to create nested structure.
+ *
+ * @param flatStructure - Flat structure object with string paths as keys
+ * @returns Nested structure object with hierarchical structure
+ *
+ * @example
+ * const flat = {
+ *   "user.name": "John",
+ *   "addresses[0].city": "San Francisco"
+ * };
+ * const nested = flatObjectToNestedObject(flat);
+ * // {
+ * //   user: { name: "John" },
+ * //   addresses: [{ city: "San Francisco" }]
+ * // }
+ */
+export function flatObjectToNestedObject<T = unknown, V = unknown>(
+  flatStructure: FlatObject<V>,
+): NestedObject<T> {
+  const result = {} as Record<string | number, unknown>;
+
+  for (const [path, value] of Object.entries(flatStructure)) {
+    setValueAtPath(result, path, value);
+  }
+
+  return result as NestedObject<T>;
+}

package/src/lib/get-arrays-diff.ts

@@ -0,0 +1,33 @@
+export interface GetArraysDiffArgs<T extends Record<string, unknown>> {
+  before: Array<T>;
+  after: Array<T>;
+  key: (item: T) => PropertyKey;
+  equals: (a: T, b: T) => boolean;
+}
+
+export function getArraysDiff<T extends Record<string, unknown>>(
+  args: GetArraysDiffArgs<T>,
+): {
+  added: Array<T>;
+  removed: Array<T>;
+  modified: Array<{ before: T; after: T }>;
+} {
+  const { before, after, key, equals } = args;
+  const isEqual = equals;
+
+  // Build lookup maps/sets for efficient comparisons by key.
+  const beforeMap = new Map(before.map((b) => [key(b), b]));
+  const afterMap = new Map(after.map((a) => [key(a), a]));
+
+  const added = after.filter((a) => !beforeMap.has(key(a)));
+  const removed = before.filter((b) => !afterMap.has(key(b)));
+
+  const modified = after
+    .map((a): { before: T; after: T } | undefined => {
+      const b = beforeMap.get(key(a));
+      return b !== undefined && !isEqual(b, a) ? { before: b, after: a } : undefined;
+    })
+    .filter((x): x is { before: T; after: T } => x !== undefined);
+
+  return { added, removed, modified };
+}

package/src/lib/nested-object-to-flat-object.ts

@@ -0,0 +1,51 @@
+import type { FlatObject, NestedObject } from "./types.ts";
+
+/**
+ * Converts a nested structure object to a flat structure object.
+ * Recursively walks the nested structure and creates path strings.
+ *
+ * @param nestedStructure - Nested structure object with hierarchical structure
+ * @returns Flat structure object with string paths as keys
+ *
+ * @example
+ * const nested = {
+ *   user: { name: "John" },
+ *   addresses: [{ city: "San Francisco" }]
+ * };
+ * const flat = nestedObjectToFlatObject(nested);
+ * // {
+ * //   "user.name": "John",
+ * //   "addresses[0].city": "San Francisco"
+ * // }
+ */
+export function nestedObjectToFlatObject<T = unknown, V = unknown>(
+  nestedStructure: NestedObject<T>,
+): FlatObject<V> {
+  const result: FlatObject<V> = {};
+
+  function walk(obj: unknown, currentPath: string) {
+    if (typeof obj !== "object" || obj === null) {
+      // Leaf node - this is a value
+      result[currentPath] = obj as V;
+      return;
+    }
+
+    if (Array.isArray(obj)) {
+      // Handle arrays
+      obj.forEach((item, index) => {
+        const newPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;
+        walk(item, newPath);
+      });
+    } else {
+      // Handle objects
+      for (const [key, value] of Object.entries(obj)) {
+        const newPath = currentPath ? `${currentPath}.${key}` : key;
+        walk(value, newPath);
+      }
+    }
+  }
+
+  walk(nestedStructure, "");
+
+  return result;
+}

package/src/lib/set-value-at-path.ts

@@ -0,0 +1,85 @@
+import { stringPathToArrayPath } from "./string-path-to-array-path.ts";
+
+/**
+ * Sets a value at a specific path within an object, creating nested objects/arrays as needed.
+ * The path is parsed using dot notation and bracket notation to navigate through the object structure.
+ * Missing intermediate objects are automatically created as objects or arrays based on the next segment type.
+ *
+ * @param object - The target object to modify (will be mutated)
+ * @param path - The path string indicating where to set the value (e.g., "user.profile[0].name")
+ * @param value - The value to set at the specified path
+ * @returns The modified input object (same reference, mutated)
+ *
+ * @example
+ * const obj = {};
+ * setValueAtPath(obj, "user.profile.name", "John");
+ * // obj becomes { user: { profile: { name: "John" } } }
+ *
+ * @example
+ * const obj = {};
+ * setValueAtPath(obj, "users[0].name", "Alice");
+ * // obj becomes { users: [{ name: "Alice" }] }
+ *
+ * @example
+ * const obj = {};
+ * setValueAtPath(obj, "config[database][host]", "localhost");
+ * // obj becomes { config: { database: { host: "localhost" } } }
+ */
+export function setValueAtPath<T extends Record<string | number, unknown>>(
+  object: T,
+  path: string,
+  value: unknown,
+): T {
+  const pathSegments = stringPathToArrayPath(path);
+
+  // Handle empty path - cannot set value on empty path.
+  if (pathSegments.length === 0) {
+    throw new Error("Cannot set value on empty path");
+  }
+
+  // Extract leading segments (all but last) and the final segment.
+  const leadingSegments = pathSegments.slice(0, -1);
+  const lastSegment = pathSegments[pathSegments.length - 1];
+
+  // Type guard for lastSegment.
+  if (lastSegment === undefined) {
+    throw new Error("Invalid path: last segment is undefined");
+  }
+
+  // Navigate through the object, creating intermediate objects/arrays as needed.
+  let currentObject: Record<string | number, unknown> = object;
+
+  for (let i = 0; i < leadingSegments.length; i++) {
+    const currentSegment = leadingSegments[i];
+
+    // Type guard for currentSegment.
+    if (currentSegment === undefined) {
+      throw new Error(`Invalid path: segment at index ${i} is undefined`);
+    }
+
+    // If the current property doesn't exist, create it.
+    if (!(currentSegment in currentObject)) {
+      // Determine the next segment to decide whether to create an object or array.
+      const nextSegment = leadingSegments[i + 1] ?? lastSegment;
+      // Create array if next segment is a number, otherwise create object.
+      currentObject[currentSegment] = typeof nextSegment === "number" ? [] : {};
+    }
+
+    // Move deeper into the structure.
+    const nextValue = currentObject[currentSegment];
+
+    // Type guard to ensure we have an object-like structure to navigate into.
+    if (typeof nextValue !== "object" || nextValue === null) {
+      throw new Error(
+        `Cannot navigate through path: expected object at segment "${currentSegment}", got ${typeof nextValue}`,
+      );
+    }
+
+    currentObject = nextValue as Record<string | number, unknown>;
+  }
+
+  // Set the final value.
+  currentObject[lastSegment] = value;
+
+  return object;
+}

package/src/lib/string-path-to-array-path.ts

@@ -0,0 +1,95 @@
+// Regular expression to match bracket notation: [key] followed by rest of path.
+const BRACKET_NOTATION_REGEX = /^\[(.+?)\](.*)$/;
+
+// Regular expression to match dot notation: optional dot followed by property
+// name and rest of path.
+const DOT_NOTATION_REGEX = /^\.?([^\.\[\]]+)(.*)$/;
+
+// Regular expression to test if a string contains only digits
+// (for array indices).
+const NUMERIC_KEY_REGEX = /^\d+$/;
+
+/**
+ * Internal recursive parser for path segments.
+ * Returns null if the path contains invalid syntax that cannot be parsed.
+ *
+ * @param currentPath - The remaining path to parse
+ * @returns Array of path segments, or null if parsing fails
+ */
+function parsePath(currentPath: string): Array<string | number> | null {
+  // Base case: empty path
+  if (currentPath.length === 0) {
+    return [];
+  }
+
+  // Try to match bracket notation first, then dot notation.
+  const bracketMatch = currentPath.match(BRACKET_NOTATION_REGEX);
+  const dotMatch = currentPath.match(DOT_NOTATION_REGEX);
+
+  if (bracketMatch) {
+    const [, key = "", rest = ""] = bracketMatch;
+    // Convert numeric keys to numbers, keep string keys as strings.
+    const parsedKey = NUMERIC_KEY_REGEX.test(key) ? Number(key) : key;
+
+    // Recursively process the rest of the path.
+    const restResult = parsePath(rest);
+
+    // If rest parsing failed (returned null), propagate failure
+    if (restResult === null) {
+      return null;
+    }
+
+    return [parsedKey, ...restResult];
+  } else if (dotMatch) {
+    const [, key = "", rest = ""] = dotMatch;
+    // Convert numeric keys to numbers, keep string keys as strings.
+    const parsedKey = NUMERIC_KEY_REGEX.test(key) ? Number(key) : key;
+
+    // Recursively process the rest of the path.
+    const restResult = parsePath(rest);
+
+    // If rest parsing failed (returned null), propagate failure
+    if (restResult === null) {
+      return null;
+    }
+
+    return [parsedKey, ...restResult];
+  }
+
+  // No pattern matched but we still have content - invalid path
+  // Return null to signal failure
+  return null;
+}
+
+/**
+ * Converts a string path to an array of path segments.
+ * Supports both bracket notation (e.g., "[0]", "[key]") and dot notation (e.g., ".prop", "prop").
+ * All numeric strings are converted to numbers regardless of notation type.
+ * If the path contains invalid syntax, returns the entire path as a single segment.
+ *
+ * @param path - The string path to convert (e.g., "user.profile[0].name")
+ * @returns Array of path segments where numeric strings become numbers
+ *
+ * @example
+ * stringPathToArrayPath("user.profile[0].name") // ["user", "profile", 0, "name"]
+ * stringPathToArrayPath("users.0[name]") // ["users", 0, "name"]
+ * stringPathToArrayPath("[0].title") // [0, "title"]
+ * stringPathToArrayPath("") // []
+ * stringPathToArrayPath("invalid[[path") // ["invalid[[path"] (invalid syntax)
+ */
+export function stringPathToArrayPath(path: string): Array<string | number> {
+  // Handle empty path.
+  if (path.length === 0) {
+    return [];
+  }
+
+  // Attempt to parse the path
+  const result = parsePath(path);
+
+  // If parsing failed, return the entire path as a single segment
+  if (result === null) {
+    return [path];
+  }
+
+  return result;
+}

package/src/lib/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Flat structure format - values mapped by string paths
+ * @example
+ * {
+ *   "user.name": "John",
+ *   "addresses[0].city": "San Francisco",
+ *   "addresses[0].state": "California"
+ * }
+ */
+export type FlatObject<V = unknown> = Record<string, V>;
+
+/**
+ * Nested structure format - values in a nested object structure
+ * @example
+ * {
+ *   user: { name: "John" },
+ *   addresses: [
+ *     { city: "San Francisco", state: "California" }
+ *   ]
+ * }
+ */
+export type NestedObject<T = unknown> = T extends object
+  ? {
+      [K in keyof T]?: T[K] extends object ? NestedObject<T[K]> : unknown;
+    }
+  : unknown;