@edge.app/x-cleaners 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# @edge.app/x-cleaners
+
+A helpful utility library of cleaners.
+
+## Install
+
+```bash
+yarn add @edge.app/x-cleaners
+bun i @edge.app/x-cleaners # or use any other package manager that supports NPM
+```
+
+## Documentation
+
+All exported cleaners are documented in the [`src/cleaners/`](./src/cleaners/) directory. Each cleaner includes TypeScript type definitions and JSDoc comments explaining its usage.

package/dist/cjs/index.js

@@ -0,0 +1,96 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  asHealingTuple: () => asHealingTuple,
+  asHealingObject: () => asHealingObject,
+  asHealingArray: () => asHealingArray
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/cleaners/asHealingArray.ts
+function asHealingArray(cleaner) {
+  return function asHealingArrayCleaner(raw) {
+    if (!Array.isArray(raw))
+      return [];
+    const out = [];
+    for (const item of raw) {
+      try {
+        out.push(cleaner(item));
+      } catch (error) {}
+    }
+    return out;
+  };
+}
+// src/cleaners/asHealingObject.ts
+var import_cleaners = require("cleaners");
+function asHealingObject(shape, fallback) {
+  if (typeof shape === "function") {
+    return function asMaybeObject(raw) {
+      if (typeof raw !== "object" || raw == null)
+        return {};
+      const out = {};
+      const keys = fallback == null ? Object.keys(raw) : Object.keys({ ...raw, ...fallback });
+      for (let i = 0;i < keys.length; ++i) {
+        const key = keys[i];
+        if (key === "__proto__")
+          continue;
+        if (fallback?.[key] == null) {
+          try {
+            out[key] = shape(raw[key]);
+          } catch (error) {}
+        } else {
+          out[key] = import_cleaners.asMaybe(shape, fallback?.[key])(raw[key]);
+        }
+      }
+      return out;
+    };
+  }
+  const safeShape = { ...shape };
+  for (const key of Object.keys(shape)) {
+    safeShape[key] = import_cleaners.asMaybe(shape[key], fallback[key]);
+  }
+  return import_cleaners.asMaybe(import_cleaners.asObject(safeShape), fallback);
+}
+// src/cleaners/asHealingTuple.ts
+var import_cleaners2 = require("cleaners");
+function asHealingTuple(cleaner, fallback) {
+  return function asMaybeTuple(raw) {
+    if (!Array.isArray(raw)) {
+      return [...fallback];
+    }
+    const out = [];
+    const length = fallback.length;
+    for (let i = 0;i < length; ++i) {
+      out.push(import_cleaners2.asMaybe(cleaner, fallback[i])(raw[i]));
+    }
+    return out;
+  };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/cleaners/asHealingArray.d.ts

@@ -0,0 +1,25 @@
+import type { Cleaner } from 'cleaners';
+/**
+ * Cleans an array that may contain errors.
+ *
+ * Invalid entries are removed from the resulting array (the healing process).
+ *
+ * @param cleaner - The cleaner function to apply to each array element
+ * @returns A cleaner function that returns an array of cleaned values
+ *
+ * @example
+ * ```typescript
+ * import { asHealingArray } from '@edge.app/x-cleaners'
+ * import { asNumber } from 'cleaners'
+ *
+ * const cleaner = asHealingArray(asNumber)
+ * const result = cleaner([1, 'invalid', 3, null, 5])
+ * // Returns: [1, 3, 5]
+ * // - Invalid entries are removed
+ *
+ * // Non-array input returns empty array
+ * const result2 = cleaner('not-an-array')
+ * // Returns: []
+ * ```
+ */
+export declare function asHealingArray<T>(cleaner: Cleaner<T>): Cleaner<T[]>;

package/dist/cleaners/asHealingObject.d.ts

@@ -0,0 +1,58 @@
+import type { Cleaner, CleanerShape } from 'cleaners';
+/**
+ * Cleans an object that may contain errors.
+ *
+ * Tries to fix individual properties when possible.
+ * For key-value objects, this will drop invalid entries unless an optional
+ * fallback is provided. For shape objects, this will use the matching property
+ * on the required fallback object.
+ *
+ * @param cleaner - The cleaner function to apply to each object value (for key-value objects)
+ * @param fallback - Optional fallback object providing default values for keys that fail validation
+ * @returns A cleaner function that returns a cleaned key-value object
+ *
+ * @example
+ * ```typescript
+ * import { asHealingObject } from '@edge.app/x-cleaners'
+ * import { asNumber } from 'cleaners'
+ *
+ * // Key-value object with fallback
+ * const cleaner = asHealingObject(asNumber, { age: 0, count: 0 })
+ * const result = cleaner({ age: '25', count: 'invalid', extra: '10' })
+ * // Returns: { age: 25, count: 0, extra: 10 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Key-value object without fallback (invalid entries are dropped)
+ * const cleaner = asHealingObject(asNumber)
+ * const result = cleaner({ valid: '42', invalid: 'not-a-number' })
+ * // Returns: { valid: 42 }
+ * ```
+ */
+export declare function asHealingObject<T>(cleaner: Cleaner<T>, fallback?: Record<string, T>): Cleaner<Record<string, T>>;
+/**
+ * Cleans a shape object that may contain errors.
+ *
+ * @param shape - A shape object with cleaner functions as values
+ * @param fallback - Required fallback object providing default values for all properties
+ * @returns A cleaner function that returns a cleaned shape object
+ *
+ * @example
+ * ```typescript
+ * import { asHealingObject } from '@edge.app/x-cleaners'
+ * import { asString, asNumber } from 'cleaners'
+ *
+ * // Shape object with fallback
+ * const shapeCleaner = asHealingObject(
+ *   { name: asString, age: asNumber },
+ *   { name: 'Unknown', age: 0 }
+ * )
+ * const result = shapeCleaner({ name: 'John', age: 'invalid' })
+ * // Returns: { name: 'John', age: 0 }
+ *
+ * const result2 = shapeCleaner({ name: 'John' })
+ * // Returns: { name: 'John', age: 0 }
+ * ```
+ */
+export declare function asHealingObject<T extends object>(shape: CleanerShape<T>, fallback: T): Cleaner<T>;

package/dist/cleaners/asHealingTuple.d.ts

@@ -0,0 +1,40 @@
+import { type Cleaner } from 'cleaners';
+/**
+ * Cleans a tuple that may contain errors.
+ *
+ * Tries to fix individual elements when possible.
+ * The fallback array determines the tuple length and provides default values
+ * for invalid entries.
+ *
+ * @param cleaner - The cleaner function to apply to each tuple element
+ * @param fallback - Array of fallback values that defines the tuple length.
+ *   If an element at index `i` fails validation, `fallback[i]` will be used.
+ * @returns A cleaner function that returns a tuple of cleaned values with fixed length
+ *
+ * @example
+ * ```typescript
+ * import { asHealingTuple } from '@edge.app/x-cleaners'
+ * import { asNumber } from 'cleaners'
+ *
+ * // Tuple with fallback (invalid entries use fallback at same index)
+ * const cleaner = asHealingTuple(asNumber, [0, 0, 0] as const)
+ * const result = cleaner([1, 'invalid', 3])
+ * // Returns: [1, 0, 3] with type [number, number, number]
+ * // - Index 0: 1 is valid number (kept)
+ * // - Index 1: 'invalid' fails validation, uses fallback[1] = 0
+ * // - Index 2: 3 is valid number (kept)
+ *
+ * // Tuple size is fixed to fallback length
+ * const cleaner2 = asHealingTuple(asNumber, [10, 20] as const)
+ * const result2 = cleaner2([1, 2, 3, 4, 5])
+ * // Returns: [1, 2] with type [number, number]
+ * // - Only first 2 elements are kept (fallback length = 2)
+ *
+ * // Non-array input returns fallback tuple
+ * const result3 = cleaner2('not-an-array')
+ * // Returns: [10, 20]
+ * ```
+ */
+export declare function asHealingTuple<T, const F extends readonly T[]>(cleaner: Cleaner<T>, fallback: F): Cleaner<{
+    -readonly [K in keyof F]: T;
+}>;

package/dist/esm/index.js

@@ -0,0 +1,64 @@
+// src/cleaners/asHealingArray.ts
+function asHealingArray(cleaner) {
+  return function asHealingArrayCleaner(raw) {
+    if (!Array.isArray(raw))
+      return [];
+    const out = [];
+    for (const item of raw) {
+      try {
+        out.push(cleaner(item));
+      } catch (error) {}
+    }
+    return out;
+  };
+}
+// src/cleaners/asHealingObject.ts
+import { asMaybe, asObject } from "cleaners";
+function asHealingObject(shape, fallback) {
+  if (typeof shape === "function") {
+    return function asMaybeObject(raw) {
+      if (typeof raw !== "object" || raw == null)
+        return {};
+      const out = {};
+      const keys = fallback == null ? Object.keys(raw) : Object.keys({ ...raw, ...fallback });
+      for (let i = 0;i < keys.length; ++i) {
+        const key = keys[i];
+        if (key === "__proto__")
+          continue;
+        if (fallback?.[key] == null) {
+          try {
+            out[key] = shape(raw[key]);
+          } catch (error) {}
+        } else {
+          out[key] = asMaybe(shape, fallback?.[key])(raw[key]);
+        }
+      }
+      return out;
+    };
+  }
+  const safeShape = { ...shape };
+  for (const key of Object.keys(shape)) {
+    safeShape[key] = asMaybe(shape[key], fallback[key]);
+  }
+  return asMaybe(asObject(safeShape), fallback);
+}
+// src/cleaners/asHealingTuple.ts
+import { asMaybe as asMaybe2 } from "cleaners";
+function asHealingTuple(cleaner, fallback) {
+  return function asMaybeTuple(raw) {
+    if (!Array.isArray(raw)) {
+      return [...fallback];
+    }
+    const out = [];
+    const length = fallback.length;
+    for (let i = 0;i < length; ++i) {
+      out.push(asMaybe2(cleaner, fallback[i])(raw[i]));
+    }
+    return out;
+  };
+}
+export {
+  asHealingTuple,
+  asHealingObject,
+  asHealingArray
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './cleaners/asHealingArray';
+export * from './cleaners/asHealingObject';
+export * from './cleaners/asHealingTuple';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@edge.app/x-cleaners",
+  "version": "0.1.0",
+  "repository": "https://github.com/EdgeApp/x-cleaners",
+  "author": "Edge (Airbitz Inc.)",
+  "contributors": [
+    "Sam Holmes <sam@edge.app>"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "source": "./src/index.ts",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "bun -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true});\"",
+    "build:esm": "bun build ./src/index.ts --outdir ./dist/esm --format esm --packages external",
+    "build:cjs": "bun build ./src/index.ts --outdir ./dist/cjs --format cjs --packages external && cp cjs-package.json ./dist/cjs/package.json",
+    "build:types": "bunx tsc --project tsconfig.build.json",
+    "build:copy-types": "bun -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('src/pouchdb-selector-core.d.ts','dist/pouchdb-selector-core.d.ts');\"",
+    "build": "bun run clean && bun run build:esm && bun run build:cjs && bun run build:types && bun run build:copy-types",
+    "precommit": "eslint --fix . && bun run test && bun run build",
+    "prepare": "(husky || true) && bun run build",
+    "release": "bun run prepare && bunx jsr publish && npm publish",
+    "test": "bun test",
+    "format": "prettier --write ."
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "eslint": "^9.39.2",
+    "eslint-config-standard-kit": "^1.0.0",
+    "husky": "^9.0.11",
+    "prettier": "^3.6.2",
+    "typescript": "^5.6.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "cleaners": "^0.3.17"
+  }
+}