@nunofyobiz/effect-extras 2.0.0 → 3.0.0

package/dist/StructX.js

@@ -0,0 +1,173 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Struct` module.
+ *
+ * @since 0.0.0
+ */
+import { Option, Predicate, Record, pipe } from "effect";
+import { dual } from "effect/Function";
+/**
+ * Builds a singleton record `{ [name]: value }` when `value` is defined, or an
+ * empty object `{}` when it is `undefined` — meant to be spread into an object
+ * literal.
+ *
+ * This is the canonical fix for `exactOptionalPropertyTypes: true` (which this
+ * repo enables for Effect Schema). Under that flag, spreading
+ * `{ key: maybeUndefined }` into an object whose key is `key?: T` is a type
+ * error: the property must be *absent*, not present-but-`undefined`. Spreading
+ * `...defined("key", maybeUndefined)` instead conditionally omits the property
+ * altogether. Note that `null` and other falsy-but-defined values (`0`, `""`,
+ * `false`) are kept — only `undefined` is dropped.
+ *
+ * @example
+ * ```ts
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Defined value → singleton record
+ * assert.deepStrictEqual(StructX.defined("name", "Ada"), { name: "Ada" })
+ *
+ * // undefined → property omitted entirely
+ * assert.deepStrictEqual(StructX.defined("name", undefined), {})
+ *
+ * // Falsy-but-defined values are kept
+ * assert.deepStrictEqual(StructX.defined("name", 0), { name: 0 })
+ *
+ * // Typical use: spread to conditionally include an optional field
+ * const maybeAge: number | undefined = undefined
+ * assert.deepStrictEqual({ id: 1, ...StructX.defined("age", maybeAge) }, {
+ *   id: 1,
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const defined = (name, value) => Predicate.isUndefined(value) ? {} : Record.singleton(name, value);
+/**
+ * Removes every property whose value is `undefined` from `record`, narrowing
+ * each remaining property type to exclude `undefined`.
+ *
+ * The bulk counterpart of {@link defined}: instead of building one optional
+ * field, it filters a whole object. Very useful for update/patch actions where
+ * `undefined` means "leave this field unchanged" while every other value —
+ * including `null`, `0`, `""`, `false`, and `Option.none()` — means "set the
+ * field to exactly this".
+ *
+ * @example
+ * ```ts
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Drops `b` (undefined) but keeps every other value, including null/0/false
+ * assert.deepStrictEqual(
+ *   StructX.filterDefined({ a: "x", b: undefined, c: 0, d: null, e: false }),
+ *   { a: "x", c: 0, d: null, e: false },
+ * )
+ * ```
+ *
+ * @category filtering
+ * @since 0.0.0
+ */
+export const filterDefined = record => Object.entries(record).reduce((accumulator, [key, value]) => ({
+  ...accumulator,
+  ...defined(key, value)
+}), {});
+/**
+ * Builds a singleton record `{ [name]: value }` when `value` is `Some`, or an
+ * empty object `{}` when it is `None` — meant to be spread into an object
+ * literal.
+ *
+ * The `Option`-valued sibling of {@link defined}: where `defined` keys off
+ * `undefined`, this keys off `Option` presence. Spread `...some("key", opt)` to
+ * conditionally include a field only when the `Option` carries a value, which
+ * stays correct under `exactOptionalPropertyTypes: true`.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Some → singleton record
+ * assert.deepStrictEqual(StructX.some("name", Option.some("Ada")), {
+ *   name: "Ada",
+ * })
+ *
+ * // None → property omitted entirely
+ * assert.deepStrictEqual(StructX.some("name", Option.none()), {})
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const some = (name, value) => Option.match(value, {
+  onSome: someValue => Record.singleton(name, someValue),
+  onNone: () => ({})
+});
+/**
+ * Like {@link some}, but with swapped argument order for piping. Returns a
+ * singleton record `{ [name]: value }` when the Option is `Some`, or an
+ * empty object `{}` when `None`.
+ *
+ * Internal-only — exists to support {@link pickSome} in data-last form.
+ * Not exported because the codebase has no direct callers.
+ */
+const someSingleton = /*#__PURE__*/dual(2, (value, name) => some(name, value));
+export function pickSome(record, key, renameKeyTo) {
+  return pipe(Record.get(record, key), Option.flatten, someSingleton(renameKeyTo ?? key));
+}
+/**
+ * Builds a singleton record `{ [name]: value }` when `value` is truthy, or an
+ * empty object `{}` otherwise — meant to be spread into an object literal.
+ *
+ * Stricter than {@link defined}: it drops not just `undefined` but every falsy
+ * value (`null`, `false`, `0`, `""`, `NaN`), and narrows the value type
+ * accordingly. Use it to spread a field only when it carries a meaningful,
+ * non-falsy value.
+ *
+ * @example
+ * ```ts
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Truthy value → singleton record
+ * assert.deepStrictEqual(StructX.truthy("name", "Ada"), { name: "Ada" })
+ *
+ * // Falsy values → property omitted entirely
+ * assert.deepStrictEqual(StructX.truthy("name", ""), {})
+ * assert.deepStrictEqual(StructX.truthy("name", 0), {})
+ * assert.deepStrictEqual(StructX.truthy("name", false), {})
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const truthy = (name, value) => Predicate.isTruthy(value) ? Record.singleton(name, value) : {};
+/**
+ * Returns `true` when `object` has `key` set to a non-nullish value, narrowing
+ * that property to `NonNullable` on the type level.
+ *
+ * A type guard combining `hasProperty` with a nullish check: after a successful
+ * test, TypeScript treats `object[key]` as present and free of `null` /
+ * `undefined`. Handy as a predicate passed to `Array.filter` to keep only the
+ * elements whose `key` is populated.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   StructX.hasNotNullableProperty({ id: "1" }, "id"),
+ *   true,
+ * )
+ *
+ * // data-last (pipeable); a null value fails the guard
+ * assert.deepStrictEqual(
+ *   pipe({ id: null }, StructX.hasNotNullableProperty("id")),
+ *   false,
+ * )
+ * ```
+ *
+ * @category refinements
+ * @since 0.0.0
+ */
+export const hasNotNullableProperty = /*#__PURE__*/dual(2, (object, key) => Predicate.hasProperty(object, key) && Predicate.isNotNullish(object[key]));
+//# sourceMappingURL=StructX.js.map

package/dist/StructX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StructX.js","names":["Option","Predicate","Record","pipe","dual","defined","name","value","isUndefined","singleton","filterDefined","record","Object","entries","reduce","accumulator","key","some","match","onSome","someValue","onNone","someSingleton","pickSome","renameKeyTo","get","flatten","truthy","isTruthy","hasNotNullableProperty","object","hasProperty","isNotNullish"],"sources":["../src/StructX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,MAAM,EAAEC,SAAS,EAAEC,MAAM,EAAEC,IAAI,QAAQ,QAAQ;AACxD,SAASC,IAAI,QAAQ,iBAAiB;AAkCtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAO,MAAMC,OAAO,GAAGA,CACrBC,IAAO,EACPC,KAAoB,KAEpBN,SAAS,CAACO,WAAW,CAACD,KAAK,CAAC,GACxB,EAAE,GACFL,MAAM,CAACO,SAAS,CAACH,IAAI,EAAEC,KAA8B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAMG,aAAa,GACxBC,MAAS,IAETC,MAAM,CAACC,OAAO,CAACF,MAAM,CAAC,CAACG,MAAM,CAC3B,CAACC,WAAW,EAAE,CAACC,GAAG,EAAET,KAAK,CAAC,MAAM;EAAE,GAAGQ,WAAW;EAAE,GAAGV,OAAO,CAACW,GAAG,EAAET,KAAK;AAAC,CAAE,CAAC,EAC3E,EAA2D,CAC5D;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMU,IAAI,GAAGA,CAClBX,IAAO,EACPC,KAAuB,KAEvBP,MAAM,CAACkB,KAAK,CAACX,KAAK,EAAE;EAClBY,MAAM,EAAGC,SAAS,IAAKlB,MAAM,CAACO,SAAS,CAACH,IAAI,EAAEc,SAAS,CAAC;EACxDC,MAAM,EAAEA,CAAA,MAAO,EAAE;CAClB,CAAC;AAEJ;;;;;;;;AAQA,MAAMC,aAAa,gBAQflB,IAAI,CACN,CAAC,EACD,CACEG,KAAuB,EACvBD,IAAO,KACmBW,IAAI,CAACX,IAAI,EAAEC,KAAK,CAAC,CAC9C;AA6CD,OAAM,SAAUgB,QAAQA,CACtBZ,MAAoC,EACpCK,GAAO,EACPQ,WAAgB;EAEhB,OAAOrB,IAAI,CACTD,MAAM,CAACuB,GAAG,CAACd,MAAM,EAAEK,GAAG,CAAC,EACvBhB,MAAM,CAAC0B,OAAO,EACdJ,aAAa,CAACE,WAAW,IAAIR,GAAG,CAAC,CAClC;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMW,MAAM,GAAGA,CACpBrB,IAAO,EACPC,KAAQ,KAERN,SAAS,CAAC2B,QAAQ,CAACrB,KAAK,CAAC,GACrBL,MAAM,CAACO,SAAS,CAACH,IAAI,EAAEC,KAAgD,CAAC,GACxE,EAAE;AAER;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMsB,sBAAsB,gBAAGzB,IAAI,CASxC,CAAC,EACD,CACE0B,MAAS,EACTd,GAAM,KAENf,SAAS,CAAC8B,WAAW,CAACD,MAAM,EAAEd,GAAG,CAAC,IAAIf,SAAS,CAAC+B,YAAY,CAACF,MAAM,CAACd,GAAG,CAAC,CAAC,CAC5E","ignoreList":[]}