@synnaxlabs/x 0.54.1 → 0.54.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/x",
-  "version": "0.54.1",
+  "version": "0.54.2",
   "type": "module",
   "description": "Common Utilities for Synnax Labs",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/x/ts",
@@ -26,9 +26,9 @@
     "typescript": "^6.0.2",
     "vite": "^8.0.3",
     "vitest": "^4.1.2",
-    "@synnaxlabs/eslint-config": "^0.0.0",
     "@synnaxlabs/tsconfig": "^0.0.0",
-    "@synnaxlabs/vite-plugin": "^0.0.0"
+    "@synnaxlabs/vite-plugin": "^0.0.0",
+    "@synnaxlabs/eslint-config": "^0.0.0"
   },
   "main": "dist/x.cjs",
   "module": "dist/x.js",

package/src/binary/codec.ts

@@ -11,6 +11,7 @@ import { type z } from "zod";
 
 import { caseconv } from "@/caseconv";
 import { narrow } from "@/narrow";
+import { zod } from "@/zod";
 
 /**
  * Codec is an entity that encodes and decodes messages to and from a
@@ -62,11 +63,11 @@ export class JSONCodec implements Codec {
   decodeString<P extends z.ZodType>(data: string, schema?: P): z.infer<P> {
     const parsed = JSON.parse(data);
     const unpacked = caseconv.snakeToCamel(parsed, { schema });
-    return schema != null ? schema.parse(unpacked) : (unpacked as z.infer<P>);
+    return schema != null ? zod.parse(schema, unpacked) : (unpacked as z.infer<P>);
   }
 
   encodeString(payload: unknown, schema?: z.ZodType): string {
-    const parsed = schema != null ? schema.parse(payload) : payload;
+    const parsed = schema != null ? zod.parse(schema, payload) : payload;
     const caseConverted = caseconv.camelToSnake(parsed ?? {}, { schema });
     return JSON.stringify(caseConverted, (_, v) => {
       if (ArrayBuffer.isView(v)) return Array.from(v as Uint8Array);

package/src/deep/atKeys.spec.ts

@@ -0,0 +1,107 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { describe, expect, it } from "vitest";
+
+import { deep } from "@/deep";
+
+describe("deep.atKeys", () => {
+  it("should return the value at a single-segment path", () => {
+    expect(deep.atKeys({ a: 1 }, ["a"])).toEqual({ present: true, value: 1 });
+  });
+
+  it("should return the value at a deeply nested path", () => {
+    expect(deep.atKeys({ a: { b: { c: "deep" } } }, ["a", "b", "c"])).toEqual({
+      present: true,
+      value: "deep",
+    });
+  });
+
+  it("should walk into arrays by numeric index", () => {
+    expect(deep.atKeys({ items: [10, 20, 30] }, ["items", 1])).toEqual({
+      present: true,
+      value: 20,
+    });
+  });
+
+  it("should return the root itself for an empty path", () => {
+    const root = { a: 1 };
+    expect(deep.atKeys(root, [])).toEqual({ present: true, value: root });
+  });
+
+  it("should mark a missing top-level key as not present", () => {
+    expect(deep.atKeys({ a: 1 }, ["b"])).toEqual({
+      present: false,
+      value: undefined,
+    });
+  });
+
+  it("should mark a missing nested key as not present", () => {
+    expect(deep.atKeys({ a: { b: 1 } }, ["a", "c"])).toEqual({
+      present: false,
+      value: undefined,
+    });
+  });
+
+  it("should return the value when a key is present with explicit undefined", () => {
+    expect(deep.atKeys({ a: undefined }, ["a"])).toEqual({
+      present: true,
+      value: undefined,
+    });
+  });
+
+  it("should return the value when a key is present with explicit null", () => {
+    expect(deep.atKeys({ a: null }, ["a"])).toEqual({
+      present: true,
+      value: null,
+    });
+  });
+
+  it("should distinguish present-but-null from missing for nested paths", () => {
+    expect(deep.atKeys({ a: { b: null } }, ["a", "b"])).toEqual({
+      present: true,
+      value: null,
+    });
+  });
+
+  it("should treat walking into a null value as not present", () => {
+    expect(deep.atKeys({ a: null }, ["a", "b"])).toEqual({
+      present: false,
+      value: undefined,
+    });
+  });
+
+  it("should treat walking into a primitive as not present", () => {
+    expect(deep.atKeys({ a: 5 }, ["a", "b"])).toEqual({
+      present: false,
+      value: undefined,
+    });
+  });
+
+  it("should not apply the deep.get 'find by .key' heuristic to arrays", () => {
+    const obj = { items: [{ key: "foo", value: 1 }] };
+    // deep.get would resolve ["items", "foo"] to the keyed item; atKeys does not.
+    expect(deep.atKeys(obj, ["items", "foo"])).toEqual({
+      present: false,
+      value: undefined,
+    });
+  });
+
+  it("should handle keys that contain literal dots unambiguously", () => {
+    const obj = { "foo.bar": 42 };
+    expect(deep.atKeys(obj, ["foo.bar"])).toEqual({ present: true, value: 42 });
+  });
+
+  it("should return not-present when root itself is null", () => {
+    expect(deep.atKeys(null, ["a"])).toEqual({
+      present: false,
+      value: undefined,
+    });
+  });
+});

package/src/deep/atKeys.ts

@@ -0,0 +1,49 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export interface AtKeysResult<V = unknown> {
+  /** True if every key in the path resolved to a property that is present on its
+   * container (via `in`), false if any segment was missing. A key with an explicit
+   * `undefined` or `null` value is still considered present. */
+  present: boolean;
+  /** The value at the path. Undefined when `present` is false. */
+  value: V | undefined;
+}
+
+/**
+ * Walks a value by a strict `PropertyKey[]` path and returns whether the path is
+ * present along with the value at that location.
+ *
+ * Differs from {@link get}/{@link has} in three important ways:
+ *
+ * 1. Takes a `PropertyKey[]` instead of a dotted string, so keys containing literal
+ *    `.` are handled unambiguously.
+ * 2. Uses plain positional key lookup (`container[key]`) without the
+ *    `defaultGetter` fallback that searches arrays for items with matching `.key`.
+ * 3. Distinguishes "key missing from container" from "key present with
+ *    `null`/`undefined` value" by using the `in` operator, which `has` does not.
+ *
+ * Intended for consumers that receive paths as `PropertyKey[]` (e.g. zod issues,
+ * JSON-pointer-like walkers) and need to render the exact state of the input,
+ * including present-but-null fields, without the ergonomic heuristics of `get`.
+ */
+export const atKeys = <V = unknown>(
+  root: unknown,
+  path: ReadonlyArray<PropertyKey>,
+): AtKeysResult<V> => {
+  let cur: unknown = root;
+  for (const key of path) {
+    if (cur == null || typeof cur !== "object")
+      return { present: false, value: undefined };
+    const container = cur as Record<PropertyKey, unknown>;
+    if (!(key in container)) return { present: false, value: undefined };
+    cur = container[key];
+  }
+  return { present: true, value: cur as V };
+};

package/src/deep/external.ts

@@ -7,6 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/deep/atKeys";
 export * from "@/deep/copy";
 export * from "@/deep/difference";
 export * from "@/deep/equal";

package/src/fmt/external.ts

@@ -0,0 +1,11 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * from "@/fmt/path";
+export * from "@/fmt/value";

package/src/fmt/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * as fmt from "@/fmt/external";

package/src/fmt/path.spec.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { describe, expect, it } from "vitest";
+
+import { fmt } from "@/fmt";
+
+describe("fmt.path", () => {
+  it("should render an empty path as <root>", () => {
+    expect(fmt.path([])).toBe("<root>");
+  });
+
+  it("should render a single string segment without a leading dot", () => {
+    expect(fmt.path(["name"])).toBe("name");
+  });
+
+  it("should join string segments with dots", () => {
+    expect(fmt.path(["a", "b", "c"])).toBe("a.b.c");
+  });
+
+  it("should render a single numeric segment as a bracket index", () => {
+    expect(fmt.path([0])).toBe("[0]");
+  });
+
+  it("should render numeric segments as bracket indices in a mixed path", () => {
+    expect(fmt.path(["items", 0, "name"])).toBe("items[0].name");
+  });
+
+  it("should render consecutive numeric segments as adjacent brackets", () => {
+    expect(fmt.path(["matrix", 1, 2])).toBe("matrix[1][2]");
+  });
+
+  it("should render a numeric root followed by a string as [0].name", () => {
+    expect(fmt.path([0, "name"])).toBe("[0].name");
+  });
+
+  it("should render a symbol segment via its String() form", () => {
+    expect(fmt.path([Symbol("foo")])).toBe("Symbol(foo)");
+  });
+});

package/src/fmt/path.ts

@@ -0,0 +1,30 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+/**
+ * Renders an object path as a human-readable string.
+ *
+ * - An empty path becomes `<root>`.
+ * - String segments are joined with `.`.
+ * - Numeric segments are rendered as bracket indices (`items[0]`).
+ *
+ * @example
+ * path([]) // "<root>"
+ * path(["config", "channels", 0, "port"]) // "config.channels[0].port"
+ */
+export const path = (segments: ReadonlyArray<PropertyKey>): string => {
+  if (segments.length === 0) return "<root>";
+  let out = "";
+  segments.forEach((p, i) => {
+    if (typeof p === "number") out += `[${p}]`;
+    else if (i === 0) out += String(p);
+    else out += `.${String(p)}`;
+  });
+  return out;
+};

package/src/fmt/value.spec.ts

@@ -0,0 +1,206 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { describe, expect, it } from "vitest";
+
+import { fmt } from "@/fmt";
+
+describe("fmt.value", () => {
+  describe("primitives", () => {
+    it("should pass strings through unchanged", () => {
+      expect(fmt.value("hello")).toBe("hello");
+    });
+
+    it("should pass an empty string through unchanged", () => {
+      expect(fmt.value("")).toBe("");
+    });
+
+    it("should pass integers through unchanged", () => {
+      expect(fmt.value(42)).toBe(42);
+    });
+
+    it("should pass floats through unchanged", () => {
+      expect(fmt.value(3.14)).toBe(3.14);
+    });
+
+    it("should pass zero through unchanged", () => {
+      expect(fmt.value(0)).toBe(0);
+    });
+
+    it("should pass NaN through unchanged", () => {
+      expect(fmt.value(NaN)).toBeNaN();
+    });
+
+    it("should pass Infinity through unchanged", () => {
+      expect(fmt.value(Infinity)).toBe(Infinity);
+    });
+
+    it("should pass true through unchanged", () => {
+      expect(fmt.value(true)).toBe(true);
+    });
+
+    it("should pass false through unchanged", () => {
+      expect(fmt.value(false)).toBe(false);
+    });
+
+    it("should pass null through unchanged", () => {
+      expect(fmt.value(null)).toBeNull();
+    });
+
+    it("should render undefined as [undefined]", () => {
+      expect(fmt.value(undefined)).toBe("[undefined]");
+    });
+
+    it("should render bigint with an n suffix", () => {
+      expect(fmt.value(BigInt(42))).toBe("42n");
+    });
+
+    it("should render 0n bigint as 0n", () => {
+      expect(fmt.value(BigInt(0))).toBe("0n");
+    });
+
+    it("should render functions as [function]", () => {
+      expect(fmt.value(() => 1)).toBe("[function]");
+    });
+
+    it("should render symbols as [symbol]", () => {
+      expect(fmt.value(Symbol("x"))).toBe("[symbol]");
+    });
+  });
+
+  describe("well-known objects", () => {
+    it("should render Date as its ISO string", () => {
+      expect(fmt.value(new Date("2026-01-01T00:00:00Z"))).toBe(
+        "2026-01-01T00:00:00.000Z",
+      );
+    });
+
+    it("should render Error as [Error: message]", () => {
+      expect(fmt.value(new Error("boom"))).toBe("[Error: boom]");
+    });
+
+    it("should render non-plain class instances as [object Object]", () => {
+      class Custom {}
+      expect(fmt.value(new Custom())).toBe("[[object Object]]");
+    });
+  });
+
+  describe("arrays", () => {
+    it("should render an empty array as an empty array", () => {
+      expect(fmt.value([])).toEqual([]);
+    });
+
+    it("should recurse into array elements preserving order and type", () => {
+      expect(fmt.value([1, "two", true, null])).toEqual([1, "two", true, null]);
+    });
+
+    it("should truncate arrays longer than maxArrayLength", () => {
+      expect(
+        fmt.value([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14], {
+          maxArrayLength: 3,
+        }),
+      ).toEqual([0, 1, 2, "…(+12 more)"]);
+    });
+
+    it("should not truncate arrays at or under maxArrayLength", () => {
+      expect(fmt.value([1, 2, 3], { maxArrayLength: 3 })).toEqual([1, 2, 3]);
+    });
+
+    it("should mark arrays beyond maxDepth without enumerating", () => {
+      expect(fmt.value([[[[[1, 2]]]]], { maxDepth: 2 })).toEqual([["[Array(1)]"]]);
+    });
+  });
+
+  describe("plain objects", () => {
+    it("should render an empty object as an empty object", () => {
+      expect(fmt.value({})).toEqual({});
+    });
+
+    it("should recurse into nested object values", () => {
+      expect(fmt.value({ a: 1, b: { c: "deep" } })).toEqual({
+        a: 1,
+        b: { c: "deep" },
+      });
+    });
+
+    it("should mark objects beyond maxDepth as [Object]", () => {
+      expect(
+        fmt.value({ a: { b: { c: { d: { e: "x" } } } } }, { maxDepth: 2 }),
+      ).toEqual({ a: { b: "[Object]" } });
+    });
+  });
+
+  describe("string truncation", () => {
+    it("should truncate strings longer than maxStringLength", () => {
+      expect(fmt.value("abcdefghij", { maxStringLength: 4 })).toBe("abcd…(+6 chars)");
+    });
+
+    it("should leave strings exactly at the limit alone", () => {
+      expect(fmt.value("abcd", { maxStringLength: 4 })).toBe("abcd");
+    });
+
+    it("should leave strings shorter than the limit alone", () => {
+      expect(fmt.value("hi", { maxStringLength: 10 })).toBe("hi");
+    });
+  });
+});
+
+describe("fmt.stringify", () => {
+  it("should render a flat object as pretty-printed JSON", () => {
+    expect(fmt.stringify({ a: 1, b: "two" })).toBe(
+      `{
+  "a": 1,
+  "b": "two"
+}`,
+    );
+  });
+
+  it("should render a nested object with indented children", () => {
+    expect(fmt.stringify({ a: { b: [1, 2] } })).toBe(
+      `{
+  "a": {
+    "b": [
+      1,
+      2
+    ]
+  }
+}`,
+    );
+  });
+
+  it("should render a truncated string inline", () => {
+    expect(fmt.stringify("abcdefghij", { maxStringLength: 4 })).toBe(
+      `"abcd…(+6 chars)"`,
+    );
+  });
+
+  it("should render a truncated array inline", () => {
+    expect(fmt.stringify([1, 2, 3, 4, 5], { maxArrayLength: 2 })).toBe(
+      `[
+  1,
+  2,
+  "…(+3 more)"
+]`,
+    );
+  });
+
+  it("should render undefined as its bracketed tag", () => {
+    expect(fmt.stringify(undefined)).toBe(`"[undefined]"`);
+  });
+
+  it("should render null as the JSON null literal", () => {
+    expect(fmt.stringify(null)).toBe("null");
+  });
+
+  it("should tolerate circular references without throwing", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(() => fmt.stringify(circular)).not.toThrow();
+  });
+});

package/src/fmt/value.ts

@@ -0,0 +1,83 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { narrow } from "@/narrow";
+
+export interface Options {
+  maxStringLength?: number;
+  maxArrayLength?: number;
+  maxDepth?: number;
+}
+
+const DEFAULT_MAX_STRING_LENGTH = 200;
+const DEFAULT_MAX_ARRAY_LENGTH = 10;
+const DEFAULT_MAX_DEPTH = 8;
+
+/**
+ * Produces a safe, JSON-friendly representation of an arbitrary value for logging and
+ * display. Strings, arrays, and object depth are capped; non-plain values such as
+ * `Date`, `Error`, functions, and symbols are rendered as short bracketed tags.
+ *
+ * Intended for user-facing error messages, debug output, and any situation where the
+ * input may be untrusted or unbounded in size. The output is always structurally
+ * cloneable and safe to JSON.stringify.
+ */
+export const value = (input: unknown, options: Options = {}): unknown => {
+  const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+  const maxArrayLength = options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+
+  const walk = (v: unknown, depth: number): unknown => {
+    if (v === null) return null;
+    if (v === undefined) return "[undefined]";
+    const t = typeof v;
+    if (t === "string") {
+      const s = v as string;
+      if (s.length > maxStringLength)
+        return `${s.slice(0, maxStringLength)}…(+${s.length - maxStringLength} chars)`;
+      return s;
+    }
+    if (t === "number" || t === "boolean") return v;
+    if (t === "bigint") return `${(v as bigint).toString()}n`;
+    if (t === "symbol" || t === "function") return `[${t}]`;
+    if (Array.isArray(v)) {
+      if (depth >= maxDepth) return `[Array(${v.length})]`;
+      const items: unknown[] = v
+        .slice(0, maxArrayLength)
+        .map((item) => walk(item, depth + 1));
+      if (v.length > maxArrayLength)
+        items.push(`…(+${v.length - maxArrayLength} more)`);
+      return items;
+    }
+    if (narrow.isPlainObject(v)) {
+      if (depth >= maxDepth) return "[Object]";
+      const out: Record<string, unknown> = {};
+      for (const [k, val] of Object.entries(v)) out[k] = walk(val, depth + 1);
+      return out;
+    }
+    if (v instanceof Date) return v.toISOString();
+    if (v instanceof Error) return `[Error: ${v.message}]`;
+    try {
+      return `[${Object.prototype.toString.call(v)}]`;
+    } catch {
+      return "[unknown]";
+    }
+  };
+
+  return walk(input, 0);
+};
+
+/**
+ * Returns a pretty-printed JSON rendering of `input` after passing it through
+ * {@link value}. Safe for untrusted or unbounded data: `value()` always returns a
+ * JSON-compatible structure (primitives, arrays, plain objects, strings), breaks
+ * cycles at the depth cap, and converts bigints/symbols/functions to strings.
+ */
+export const stringify = (input: unknown, options: Options = {}): string =>
+  JSON.stringify(value(input, options), null, 2);

package/src/index.ts

@@ -21,6 +21,7 @@ export * from "@/debounce";
 export * from "@/deep";
 export * from "@/destructor";
 export * from "@/errors";
+export * from "@/fmt";
 export * from "@/id";
 export * from "@/instance";
 export * from "@/json";

package/src/narrow/narrow.spec.ts

@@ -67,4 +67,47 @@ describe("narrow", () => {
       expect(narrow.isObject(/test/)).toBe(true);
     });
   });
+
+  describe("isPlainObject", () => {
+    it("should return true for object literals", () => {
+      expect(narrow.isPlainObject({})).toBe(true);
+      expect(narrow.isPlainObject({ a: 1 })).toBe(true);
+    });
+
+    it("should return true for objects with a null prototype", () => {
+      expect(narrow.isPlainObject(Object.create(null))).toBe(true);
+    });
+
+    it("should return false for arrays", () => {
+      expect(narrow.isPlainObject([])).toBe(false);
+      expect(narrow.isPlainObject([1, 2])).toBe(false);
+    });
+
+    it("should return false for null and undefined", () => {
+      expect(narrow.isPlainObject(null)).toBe(false);
+      expect(narrow.isPlainObject(undefined)).toBe(false);
+    });
+
+    it("should return false for primitives", () => {
+      expect(narrow.isPlainObject(0)).toBe(false);
+      expect(narrow.isPlainObject("string")).toBe(false);
+      expect(narrow.isPlainObject(true)).toBe(false);
+      expect(narrow.isPlainObject(Symbol("x"))).toBe(false);
+      expect(narrow.isPlainObject(42n)).toBe(false);
+    });
+
+    it("should return false for class instances", () => {
+      class Custom {}
+      expect(narrow.isPlainObject(new Custom())).toBe(false);
+      expect(narrow.isPlainObject(new Date())).toBe(false);
+      expect(narrow.isPlainObject(new Map())).toBe(false);
+      expect(narrow.isPlainObject(new Error())).toBe(false);
+      expect(narrow.isPlainObject(/regex/)).toBe(false);
+    });
+
+    it("should return false for functions", () => {
+      expect(narrow.isPlainObject(() => 1)).toBe(false);
+      expect(narrow.isPlainObject(async () => 1)).toBe(false);
+    });
+  });
 });

package/src/narrow/narrow.ts

@@ -18,3 +18,18 @@ export type IsUndefined<T> = [T] extends [undefined] // T can be assigned to und
 export const isObject = <T extends record.Unknown = record.Unknown>(
   item?: unknown,
 ): item is T => item != null && typeof item === "object" && !Array.isArray(item);
+
+/**
+ * A stricter version of {@link isObject} that additionally rejects class instances,
+ * arrays, and any non-`Object.prototype` objects. Returns true only for plain objects
+ * created via `{}`, `Object.create(null)`, or an object literal.
+ *
+ * Useful for walkers that need to distinguish "plain data bag" from "wrapped instance"
+ * (e.g. `Date`, `Map`, `Error`), which `isObject` treats the same.
+ */
+export const isPlainObject = (item?: unknown): item is Record<string, unknown> => {
+  if (item == null || typeof item !== "object") return false;
+  if (Array.isArray(item)) return false;
+  const proto = Object.getPrototypeOf(item);
+  return proto === Object.prototype || proto === null;
+};