payload-sanitizer 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,131 @@
+# payload-sanitizer
+
+Tiny zero‑dependency sanitizer for JS/TS payloads that removes common junk (empty strings, whitespace-only strings, `null`, `undefined`, optional dash marker, `NaN`) without mutating the original value. Works in both frontend and backend code.
+
+## Install
+
+```bash
+# pnpm
+pnpm add payload-sanitizer
+
+# npm
+npm i payload-sanitizer
+
+# yarn
+yarn add payload-sanitizer
+```
+
+## Quick start
+
+```ts
+import { sanitize } from "payload-sanitizer";
+
+const input = {
+  trxId: "",
+  status: "-",
+  fromDate: " 2026-02-01 ",
+  toDate: null,
+  page: 1,
+  includeInactive: false,
+};
+
+const clean = sanitize(input, {
+  drop: ["undefined", "null", "emptyString", "whitespaceString", "dash"],
+});
+
+console.log(clean);
+// {
+//   fromDate: "2026-02-01",
+//   page: 1,
+//   includeInactive: false
+// }
+```
+
+## Why this instead of validation libraries?
+
+Validation libs (e.g., Zod) parse **against a schema**. `payload-sanitizer` just **cleans/normalizes** data with simple rules—no schema required. They pair well:
+
+```ts
+const cleaned = sanitize(formValues);
+const parsed = schema.parse(cleaned);
+```
+
+## API
+
+### `sanitize(payload, options?)`
+
+Returns a cleaned clone of `payload` (objects and arrays) without mutating the input.
+
+**Options**
+- `deep` (default `true`): recurse into nested objects.
+- `trimStrings` (default `true`): `value.trim()` on strings before checks.
+- `cleanArrays` (default `true`): sanitize array items and drop ones that should be removed.
+- `drop` (defaults to `["undefined","null","emptyString","whitespaceString"]`): presets to remove. Presets: `"undefined" | "null" | "emptyString" | "whitespaceString" | "dash" | "nan"`.
+- `keepKeys`: key names to always keep even if value looks droppable.
+- `dropKeys`: key names to always remove.
+- `dropValues`: explicit values to remove (uses `Object.is`).
+- `shouldDrop(value, keyPath)`: custom predicate; return `true` to drop. `keyPath` is an array of keys/indexes from root.
+
+Notes:
+- `0`, `false`, and `""` inside `keepKeys` are preserved by design.
+- If everything is dropped, arrays become `[]`, objects become `{}`; primitives are returned as-is.
+
+### `sanitize.with(baseOptions)`
+
+Creates a preconfigured sanitizer.
+
+```ts
+const sanitizeSearch = sanitize.with({
+  drop: ["undefined", "null", "emptyString", "whitespaceString", "dash"],
+});
+
+sanitizeSearch({ q: "  hello ", status: "-" });
+// { q: "hello" }
+```
+
+### `createSanitizer(baseOptions)`
+
+Factory equivalent to `sanitize.with`.
+
+```ts
+import { createSanitizer } from "payload-sanitizer";
+const sanitizePayload = createSanitizer({ deep: true });
+```
+
+## Common patterns
+
+- **Frontend forms** — clean before sending:
+  ```ts
+  await api.post("/search", sanitize(values));
+  ```
+- **Backend filters** — strip empty query params:
+  ```ts
+  const filters = sanitize(req.query, { drop: ["dash"] });
+  db.find(filters);
+  ```
+- **Custom rule** — drop empty `filters` objects:
+  ```ts
+  sanitize(payload, {
+    shouldDrop: (value, path) =>
+      path.at(-1) === "filters" &&
+      typeof value === "object" &&
+      value !== null &&
+      Object.keys(value as any).length === 0,
+  });
+  ```
+- **Drop exact values**:
+  ```ts
+  sanitize(data, { dropValues: ["N/A", Number.NaN] });
+  ```
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,128 @@
+'use strict';
+
+// src/index.ts
+var DEFAULT_DROP = [
+  "undefined",
+  "null",
+  "emptyString",
+  "whitespaceString"
+];
+var DEFAULT_OPTIONS = {
+  deep: true,
+  trimStrings: true,
+  cleanArrays: true,
+  drop: DEFAULT_DROP
+};
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function normalizeValue(value, opts) {
+  if (typeof value === "string" && opts.trimStrings) {
+    return value.trim();
+  }
+  return value;
+}
+function shouldDropPreset(value, drop) {
+  for (const d of drop) {
+    switch (d) {
+      case "undefined":
+        if (value === void 0) return true;
+        break;
+      case "null":
+        if (value === null) return true;
+        break;
+      case "emptyString":
+        if (value === "") return true;
+        break;
+      case "whitespaceString":
+        if (typeof value === "string" && value.trim() === "") return true;
+        break;
+      case "dash":
+        if (value === "-") return true;
+        break;
+      case "nan":
+        if (typeof value === "number" && Number.isNaN(value)) return true;
+        break;
+    }
+  }
+  return false;
+}
+function shouldDropExact(value, exactValues) {
+  if (!exactValues || exactValues.length === 0) return false;
+  for (const v of exactValues) {
+    if (Object.is(value, v)) return true;
+  }
+  return false;
+}
+function hasKey(list, key) {
+  return !!list && list.includes(key);
+}
+function sanitizeAny(input, options, path) {
+  const normalized = normalizeValue(input, options);
+  if (shouldDropPreset(normalized, options.drop)) return void 0;
+  if (shouldDropExact(normalized, options.dropValues)) return void 0;
+  if (options.shouldDrop?.(normalized, path)) return void 0;
+  if (Array.isArray(normalized)) {
+    if (!options.cleanArrays) return normalized.slice();
+    const out = [];
+    for (let i = 0; i < normalized.length; i++) {
+      const next = sanitizeAny(normalized[i], options, path.concat(i));
+      if (next !== void 0) out.push(next);
+    }
+    return out;
+  }
+  if (isPlainObject(normalized)) {
+    if (!options.deep) {
+      const out2 = {};
+      for (const [k, v] of Object.entries(normalized)) {
+        if (hasKey(options.dropKeys, k)) continue;
+        if (hasKey(options.keepKeys, k)) {
+          out2[k] = v;
+          continue;
+        }
+        const next = sanitizeAny(v, options, path.concat(k));
+        if (next !== void 0) out2[k] = next;
+      }
+      return out2;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(normalized)) {
+      if (hasKey(options.dropKeys, k)) continue;
+      if (hasKey(options.keepKeys, k)) {
+        out[k] = v;
+        continue;
+      }
+      const next = sanitizeAny(v, options, path.concat(k));
+      if (next !== void 0) out[k] = next;
+    }
+    return out;
+  }
+  return normalized;
+}
+function sanitize(payload, options = {}) {
+  const merged = {
+    ...DEFAULT_OPTIONS,
+    ...options,
+    drop: options.drop ?? DEFAULT_OPTIONS.drop
+  };
+  const result = sanitizeAny(payload, merged, []);
+  if (result === void 0) {
+    if (isPlainObject(payload)) return {};
+    if (Array.isArray(payload)) return [];
+    return payload;
+  }
+  return result;
+}
+var createSanitizer = (baseOptions = {}) => {
+  return (payload, options = {}) => sanitize(payload, { ...baseOptions, ...options });
+};
+sanitize.with = (baseOptions = {}) => createSanitizer(baseOptions);
+var sanitizeWith = sanitize.with;
+
+exports.createSanitizer = createSanitizer;
+exports.sanitize = sanitize;
+exports.sanitizeWith = sanitizeWith;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["out"],"mappings":"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","file":"index.cjs","sourcesContent":["export type DropPreset =\n  | \"null\"\n  | \"undefined\"\n  | \"emptyString\"\n  | \"whitespaceString\"\n  | \"dash\"\n  | \"nan\";\n\nexport type KeyPath = Array<string | number>;\n\nexport type SanitizeOptions = {\n  deep?: boolean;\n  trimStrings?: boolean;\n  cleanArrays?: boolean;\n  drop?: DropPreset[];\n  keepKeys?: string[];\n  dropKeys?: string[];\n  dropValues?: unknown[];\n  shouldDrop?: (value: unknown, keyPath: KeyPath) => boolean;\n};\n\nconst DEFAULT_DROP: DropPreset[] = [\n  \"undefined\",\n  \"null\",\n  \"emptyString\",\n  \"whitespaceString\",\n];\n\nconst DEFAULT_OPTIONS: Required<\n  Pick<SanitizeOptions, \"deep\" | \"trimStrings\" | \"cleanArrays\">\n> & { drop: DropPreset[] } = {\n  deep: true,\n  trimStrings: true,\n  cleanArrays: true,\n  drop: DEFAULT_DROP,\n};\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\nfunction normalizeValue(\n  value: unknown,\n  opts: Required<typeof DEFAULT_OPTIONS>,\n) {\n  if (typeof value === \"string\" && opts.trimStrings) {\n    return value.trim();\n  }\n  return value;\n}\n\nfunction shouldDropPreset(value: unknown, drop: DropPreset[]): boolean {\n  for (const d of drop) {\n    switch (d) {\n      case \"undefined\":\n        if (value === undefined) return true;\n        break;\n      case \"null\":\n        if (value === null) return true;\n        break;\n      case \"emptyString\":\n        if (value === \"\") return true;\n        break;\n      case \"whitespaceString\":\n        // only matters if trimStrings is false; but still safe:\n        if (typeof value === \"string\" && value.trim() === \"\") return true;\n        break;\n      case \"dash\":\n        if (value === \"-\") return true;\n        break;\n      case \"nan\":\n        if (typeof value === \"number\" && Number.isNaN(value)) return true;\n        break;\n    }\n  }\n  return false;\n}\n\nfunction shouldDropExact(value: unknown, exactValues?: unknown[]): boolean {\n  if (!exactValues || exactValues.length === 0) return false;\n  for (const v of exactValues) {\n    if (Object.is(value, v)) return true;\n  }\n  return false;\n}\n\nfunction hasKey(list: string[] | undefined, key: string): boolean {\n  return !!list && list.includes(key);\n}\n\nfunction sanitizeAny(\n  input: unknown,\n  options: Required<typeof DEFAULT_OPTIONS> & SanitizeOptions,\n  path: KeyPath,\n): unknown {\n  const normalized = normalizeValue(input, options);\n\n  if (shouldDropPreset(normalized, options.drop)) return undefined;\n  if (shouldDropExact(normalized, options.dropValues)) return undefined;\n  if (options.shouldDrop?.(normalized, path)) return undefined;\n\n  if (Array.isArray(normalized)) {\n    if (!options.cleanArrays) return normalized.slice();\n    const out: unknown[] = [];\n    for (let i = 0; i < normalized.length; i++) {\n      const next = sanitizeAny(normalized[i], options, path.concat(i));\n      if (next !== undefined) out.push(next);\n    }\n    return out;\n  }\n\n  if (isPlainObject(normalized)) {\n    if (!options.deep) {\n      const out: Record<string, unknown> = {};\n      for (const [k, v] of Object.entries(normalized)) {\n        if (hasKey(options.dropKeys, k)) continue;\n        if (hasKey(options.keepKeys, k)) {\n          out[k] = v;\n          continue;\n        }\n        const next = sanitizeAny(v, options, path.concat(k));\n        if (next !== undefined) out[k] = next;\n      }\n      return out;\n    }\n\n    const out: Record<string, unknown> = {};\n    for (const [k, v] of Object.entries(normalized)) {\n      if (hasKey(options.dropKeys, k)) continue;\n\n      if (hasKey(options.keepKeys, k)) {\n        out[k] = v;\n        continue;\n      }\n\n      const next = sanitizeAny(v, options, path.concat(k));\n      if (next !== undefined) out[k] = next;\n    }\n    return out;\n  }\n\n  return normalized;\n}\n\nexport function sanitize<T>(payload: T, options: SanitizeOptions = {}): T {\n  const merged = {\n    ...DEFAULT_OPTIONS,\n    ...options,\n    drop: options.drop ?? DEFAULT_OPTIONS.drop,\n  };\n\n  const result = sanitizeAny(payload, merged, []);\n\n  if (result === undefined) {\n    if (isPlainObject(payload)) return {} as T;\n    if (Array.isArray(payload)) return [] as T;\n    return payload;\n  }\n\n  return result as T;\n}\n\ntype SanitizerFn = {\n  <T>(payload: T, options?: SanitizeOptions): T;\n  with: (baseOptions?: SanitizeOptions) => ReturnType<typeof createSanitizer>;\n};\n\nexport const createSanitizer = (baseOptions: SanitizeOptions = {}) => {\n  return <T>(payload: T, options: SanitizeOptions = {}) =>\n    sanitize(payload, { ...baseOptions, ...options });\n};\n\n(sanitize as SanitizerFn).with = (baseOptions: SanitizeOptions = {}) =>\n  createSanitizer(baseOptions);\n\nexport const sanitizeWith = (sanitize as SanitizerFn).with;\n"]}

package/dist/index.d.cts

@@ -0,0 +1,17 @@
+type DropPreset = "null" | "undefined" | "emptyString" | "whitespaceString" | "dash" | "nan";
+type KeyPath = Array<string | number>;
+type SanitizeOptions = {
+    deep?: boolean;
+    trimStrings?: boolean;
+    cleanArrays?: boolean;
+    drop?: DropPreset[];
+    keepKeys?: string[];
+    dropKeys?: string[];
+    dropValues?: unknown[];
+    shouldDrop?: (value: unknown, keyPath: KeyPath) => boolean;
+};
+declare function sanitize<T>(payload: T, options?: SanitizeOptions): T;
+declare const createSanitizer: (baseOptions?: SanitizeOptions) => <T>(payload: T, options?: SanitizeOptions) => T;
+declare const sanitizeWith: (baseOptions?: SanitizeOptions) => ReturnType<typeof createSanitizer>;
+
+export { type DropPreset, type KeyPath, type SanitizeOptions, createSanitizer, sanitize, sanitizeWith };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+type DropPreset = "null" | "undefined" | "emptyString" | "whitespaceString" | "dash" | "nan";
+type KeyPath = Array<string | number>;
+type SanitizeOptions = {
+    deep?: boolean;
+    trimStrings?: boolean;
+    cleanArrays?: boolean;
+    drop?: DropPreset[];
+    keepKeys?: string[];
+    dropKeys?: string[];
+    dropValues?: unknown[];
+    shouldDrop?: (value: unknown, keyPath: KeyPath) => boolean;
+};
+declare function sanitize<T>(payload: T, options?: SanitizeOptions): T;
+declare const createSanitizer: (baseOptions?: SanitizeOptions) => <T>(payload: T, options?: SanitizeOptions) => T;
+declare const sanitizeWith: (baseOptions?: SanitizeOptions) => ReturnType<typeof createSanitizer>;
+
+export { type DropPreset, type KeyPath, type SanitizeOptions, createSanitizer, sanitize, sanitizeWith };

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/index.ts
+var DEFAULT_DROP = [
+  "undefined",
+  "null",
+  "emptyString",
+  "whitespaceString"
+];
+var DEFAULT_OPTIONS = {
+  deep: true,
+  trimStrings: true,
+  cleanArrays: true,
+  drop: DEFAULT_DROP
+};
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function normalizeValue(value, opts) {
+  if (typeof value === "string" && opts.trimStrings) {
+    return value.trim();
+  }
+  return value;
+}
+function shouldDropPreset(value, drop) {
+  for (const d of drop) {
+    switch (d) {
+      case "undefined":
+        if (value === void 0) return true;
+        break;
+      case "null":
+        if (value === null) return true;
+        break;
+      case "emptyString":
+        if (value === "") return true;
+        break;
+      case "whitespaceString":
+        if (typeof value === "string" && value.trim() === "") return true;
+        break;
+      case "dash":
+        if (value === "-") return true;
+        break;
+      case "nan":
+        if (typeof value === "number" && Number.isNaN(value)) return true;
+        break;
+    }
+  }
+  return false;
+}
+function shouldDropExact(value, exactValues) {
+  if (!exactValues || exactValues.length === 0) return false;
+  for (const v of exactValues) {
+    if (Object.is(value, v)) return true;
+  }
+  return false;
+}
+function hasKey(list, key) {
+  return !!list && list.includes(key);
+}
+function sanitizeAny(input, options, path) {
+  const normalized = normalizeValue(input, options);
+  if (shouldDropPreset(normalized, options.drop)) return void 0;
+  if (shouldDropExact(normalized, options.dropValues)) return void 0;
+  if (options.shouldDrop?.(normalized, path)) return void 0;
+  if (Array.isArray(normalized)) {
+    if (!options.cleanArrays) return normalized.slice();
+    const out = [];
+    for (let i = 0; i < normalized.length; i++) {
+      const next = sanitizeAny(normalized[i], options, path.concat(i));
+      if (next !== void 0) out.push(next);
+    }
+    return out;
+  }
+  if (isPlainObject(normalized)) {
+    if (!options.deep) {
+      const out2 = {};
+      for (const [k, v] of Object.entries(normalized)) {
+        if (hasKey(options.dropKeys, k)) continue;
+        if (hasKey(options.keepKeys, k)) {
+          out2[k] = v;
+          continue;
+        }
+        const next = sanitizeAny(v, options, path.concat(k));
+        if (next !== void 0) out2[k] = next;
+      }
+      return out2;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(normalized)) {
+      if (hasKey(options.dropKeys, k)) continue;
+      if (hasKey(options.keepKeys, k)) {
+        out[k] = v;
+        continue;
+      }
+      const next = sanitizeAny(v, options, path.concat(k));
+      if (next !== void 0) out[k] = next;
+    }
+    return out;
+  }
+  return normalized;
+}
+function sanitize(payload, options = {}) {
+  const merged = {
+    ...DEFAULT_OPTIONS,
+    ...options,
+    drop: options.drop ?? DEFAULT_OPTIONS.drop
+  };
+  const result = sanitizeAny(payload, merged, []);
+  if (result === void 0) {
+    if (isPlainObject(payload)) return {};
+    if (Array.isArray(payload)) return [];
+    return payload;
+  }
+  return result;
+}
+var createSanitizer = (baseOptions = {}) => {
+  return (payload, options = {}) => sanitize(payload, { ...baseOptions, ...options });
+};
+sanitize.with = (baseOptions = {}) => createSanitizer(baseOptions);
+var sanitizeWith = sanitize.with;
+
+export { createSanitizer, sanitize, sanitizeWith };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["out"],"mappings":"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","file":"index.js","sourcesContent":["export type DropPreset =\n  | \"null\"\n  | \"undefined\"\n  | \"emptyString\"\n  | \"whitespaceString\"\n  | \"dash\"\n  | \"nan\";\n\nexport type KeyPath = Array<string | number>;\n\nexport type SanitizeOptions = {\n  deep?: boolean;\n  trimStrings?: boolean;\n  cleanArrays?: boolean;\n  drop?: DropPreset[];\n  keepKeys?: string[];\n  dropKeys?: string[];\n  dropValues?: unknown[];\n  shouldDrop?: (value: unknown, keyPath: KeyPath) => boolean;\n};\n\nconst DEFAULT_DROP: DropPreset[] = [\n  \"undefined\",\n  \"null\",\n  \"emptyString\",\n  \"whitespaceString\",\n];\n\nconst DEFAULT_OPTIONS: Required<\n  Pick<SanitizeOptions, \"deep\" | \"trimStrings\" | \"cleanArrays\">\n> & { drop: DropPreset[] } = {\n  deep: true,\n  trimStrings: true,\n  cleanArrays: true,\n  drop: DEFAULT_DROP,\n};\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\nfunction normalizeValue(\n  value: unknown,\n  opts: Required<typeof DEFAULT_OPTIONS>,\n) {\n  if (typeof value === \"string\" && opts.trimStrings) {\n    return value.trim();\n  }\n  return value;\n}\n\nfunction shouldDropPreset(value: unknown, drop: DropPreset[]): boolean {\n  for (const d of drop) {\n    switch (d) {\n      case \"undefined\":\n        if (value === undefined) return true;\n        break;\n      case \"null\":\n        if (value === null) return true;\n        break;\n      case \"emptyString\":\n        if (value === \"\") return true;\n        break;\n      case \"whitespaceString\":\n        // only matters if trimStrings is false; but still safe:\n        if (typeof value === \"string\" && value.trim() === \"\") return true;\n        break;\n      case \"dash\":\n        if (value === \"-\") return true;\n        break;\n      case \"nan\":\n        if (typeof value === \"number\" && Number.isNaN(value)) return true;\n        break;\n    }\n  }\n  return false;\n}\n\nfunction shouldDropExact(value: unknown, exactValues?: unknown[]): boolean {\n  if (!exactValues || exactValues.length === 0) return false;\n  for (const v of exactValues) {\n    if (Object.is(value, v)) return true;\n  }\n  return false;\n}\n\nfunction hasKey(list: string[] | undefined, key: string): boolean {\n  return !!list && list.includes(key);\n}\n\nfunction sanitizeAny(\n  input: unknown,\n  options: Required<typeof DEFAULT_OPTIONS> & SanitizeOptions,\n  path: KeyPath,\n): unknown {\n  const normalized = normalizeValue(input, options);\n\n  if (shouldDropPreset(normalized, options.drop)) return undefined;\n  if (shouldDropExact(normalized, options.dropValues)) return undefined;\n  if (options.shouldDrop?.(normalized, path)) return undefined;\n\n  if (Array.isArray(normalized)) {\n    if (!options.cleanArrays) return normalized.slice();\n    const out: unknown[] = [];\n    for (let i = 0; i < normalized.length; i++) {\n      const next = sanitizeAny(normalized[i], options, path.concat(i));\n      if (next !== undefined) out.push(next);\n    }\n    return out;\n  }\n\n  if (isPlainObject(normalized)) {\n    if (!options.deep) {\n      const out: Record<string, unknown> = {};\n      for (const [k, v] of Object.entries(normalized)) {\n        if (hasKey(options.dropKeys, k)) continue;\n        if (hasKey(options.keepKeys, k)) {\n          out[k] = v;\n          continue;\n        }\n        const next = sanitizeAny(v, options, path.concat(k));\n        if (next !== undefined) out[k] = next;\n      }\n      return out;\n    }\n\n    const out: Record<string, unknown> = {};\n    for (const [k, v] of Object.entries(normalized)) {\n      if (hasKey(options.dropKeys, k)) continue;\n\n      if (hasKey(options.keepKeys, k)) {\n        out[k] = v;\n        continue;\n      }\n\n      const next = sanitizeAny(v, options, path.concat(k));\n      if (next !== undefined) out[k] = next;\n    }\n    return out;\n  }\n\n  return normalized;\n}\n\nexport function sanitize<T>(payload: T, options: SanitizeOptions = {}): T {\n  const merged = {\n    ...DEFAULT_OPTIONS,\n    ...options,\n    drop: options.drop ?? DEFAULT_OPTIONS.drop,\n  };\n\n  const result = sanitizeAny(payload, merged, []);\n\n  if (result === undefined) {\n    if (isPlainObject(payload)) return {} as T;\n    if (Array.isArray(payload)) return [] as T;\n    return payload;\n  }\n\n  return result as T;\n}\n\ntype SanitizerFn = {\n  <T>(payload: T, options?: SanitizeOptions): T;\n  with: (baseOptions?: SanitizeOptions) => ReturnType<typeof createSanitizer>;\n};\n\nexport const createSanitizer = (baseOptions: SanitizeOptions = {}) => {\n  return <T>(payload: T, options: SanitizeOptions = {}) =>\n    sanitize(payload, { ...baseOptions, ...options });\n};\n\n(sanitize as SanitizerFn).with = (baseOptions: SanitizeOptions = {}) =>\n  createSanitizer(baseOptions);\n\nexport const sanitizeWith = (sanitize as SanitizerFn).with;\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "payload-sanitizer",
+  "version": "0.0.1",
+  "description": "Tiny zero-dependency payload sanitizer for JS/TS (frontend + backend).",
+  "keywords": [
+    "sanitize",
+    "payload",
+    "clean",
+    "typescript",
+    "utils"
+  ],
+  "license": "MIT",
+  "author": "Mohitul Islam",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "prepublishOnly": "pnpm build && pnpm test && pnpm typecheck"
+  },
+  "packageManager": "pnpm@10.29.3",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}