@nunofyobiz/effect-extras 0.0.1

package/src/SchemaX/SchemaX.ts

@@ -0,0 +1,324 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Schema` module.
+ *
+ * @since 0.0.0
+ */
+import { BigInt, Schema, SchemaGetter, Struct } from "effect";
+
+/**
+ * A `Schema` for a non-empty string that is trimmed on both decode and encode.
+ *
+ * Leading and trailing whitespace is stripped, and the resulting value must be
+ * non-empty — so a whitespace-only input (e.g. `"   "`) fails the
+ * `NonEmptyString` refinement after trimming. Use it wherever user-supplied text
+ * should be normalized and guaranteed to carry content.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * const decoded = Effect.runSync(
+ *   Schema.decodeEffect(SchemaX.TrimmedNonEmptyString)("  hello  "),
+ * )
+ * assert.deepStrictEqual(decoded, "hello")
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const TrimmedNonEmptyString = Schema.NonEmptyString.pipe(
+  Schema.decode({
+    decode: SchemaGetter.transform((s) => s.trim()),
+    encode: SchemaGetter.transform((s) => s.trim()),
+  }),
+);
+
+/**
+ * A `Schema` for a URL-safe file path built on top of {@link
+ * TrimmedNonEmptyString}.
+ *
+ * On decode the path is `decodeURIComponent`-ed (percent-escapes are expanded);
+ * on encode it is `encodeURIComponent`-ed back into its URL-safe form. The
+ * underlying value is also trimmed and required to be non-empty. Use it at the
+ * boundary between stored/transmitted encoded paths and the decoded paths your
+ * code works with.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * // Decoding expands percent-escapes
+ * const decoded = Effect.runSync(
+ *   Schema.decodeEffect(SchemaX.URLSafeFilePath)("a%2Fb.txt"),
+ * )
+ * assert.deepStrictEqual(decoded, "a/b.txt")
+ *
+ * // Encoding produces the URL-safe form
+ * const encoded = Effect.runSync(
+ *   Schema.encodeEffect(SchemaX.URLSafeFilePath)("a/b.txt"),
+ * )
+ * assert.deepStrictEqual(encoded, "a%2Fb.txt")
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const URLSafeFilePath = TrimmedNonEmptyString.pipe(
+  Schema.decode({
+    decode: SchemaGetter.transform((path) => decodeURIComponent(path)),
+    encode: SchemaGetter.transform((path) => encodeURIComponent(path)),
+  }),
+);
+
+// Internal — only used to construct nonNegativeBigInt below.
+const clampMinBigInt =
+  (min: bigint) =>
+  <S extends Schema.Schema<bigint>>(schema: S) =>
+    schema.pipe(
+      Schema.decode({
+        decode: SchemaGetter.transform((value) => BigInt.max(value, min)),
+        encode: SchemaGetter.transform((value) => BigInt.max(value, min)),
+      }),
+    );
+
+/**
+ * Transforms a `bigint` `Schema` so its value is clamped to be non-negative,
+ * mapping any value below `0n` up to `0n` on both decode and encode.
+ *
+ * Unlike a refinement that *rejects* negative input, this *coerces* it: a
+ * negative `bigint` decodes to `0n` rather than failing. Apply it to a `bigint`
+ * schema whenever negative magnitudes are meaningless and should be floored at
+ * zero rather than treated as errors.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * const NonNegative = SchemaX.nonNegativeBigInt(Schema.BigInt)
+ *
+ * // Negative values are clamped up to 0n
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Schema.decodeEffect(NonNegative)(-5n)),
+ *   0n,
+ * )
+ *
+ * // Non-negative values pass through unchanged
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Schema.decodeEffect(NonNegative)(7n)),
+ *   7n,
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const nonNegativeBigInt = clampMinBigInt(0n);
+
+/**
+ * Extracts the "constructor input" type of a `Schema` — what `.make({...})`
+ * accepts.
+ *
+ * Differs from `S["Type"]` (the decoded type) in that fields carrying
+ * constructor defaults (e.g. an `Overrideable` timestamp) are *optional* in
+ * `MakeIn` but *required* in `Type`. Use it in signatures that accept a value to
+ * construct, so callers can pass a plain object literal without supplying the
+ * defaulted, override-branded fields.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * const Person = Schema.Struct({ name: Schema.String, age: Schema.Number })
+ *
+ * const input: SchemaX.MakeIn<typeof Person> = { name: "Ada", age: 36 }
+ *
+ * assert.deepStrictEqual(input, { name: "Ada", age: 36 })
+ * ```
+ *
+ * @category models
+ * @since 0.0.0
+ */
+export type MakeIn<S extends { readonly "~type.make.in": unknown }> =
+  S["~type.make.in"];
+
+// ---------------------------------------------------------------------------
+// Schema.Struct utilities — v4 removed the `.pick(...)`, `.omit(...)`, and
+// `Schema.partial(...)` methods that v3 had on `Schema.Struct` instances. These
+// helpers restore the same ergonomics on top of v4's `mapFields` primitive.
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a new `Schema.Struct` containing only the named `keys` of `schema`.
+ *
+ * Restores the v3 ergonomics of `mySchema.pick("a", "b")` — v4 removed the
+ * `.pick(...)` method from `Schema.Struct` instances, so this rebuilds it on top
+ * of v4's `mapFields` primitive. Each picked field keeps its original schema,
+ * including any refinements.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * const Source = Schema.Struct({
+ *   a: Schema.Number,
+ *   b: Schema.String,
+ *   c: Schema.Boolean,
+ * })
+ *
+ * const Picked = SchemaX.pick(Source, "a", "b")
+ *
+ * const decoded = Effect.runSync(
+ *   Schema.decodeEffect(Picked)({ a: 1, b: "hi" }),
+ * )
+ * assert.deepStrictEqual(decoded, { a: 1, b: "hi" })
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const pick = <
+  const Fields extends Schema.Struct.Fields,
+  const Keys extends readonly (keyof Fields & string)[],
+>(
+  schema: Schema.Struct<Fields>,
+  ...keys: Keys
+): Schema.Struct<Pick<Fields, Keys[number]>> =>
+  schema.mapFields(
+    (fields) =>
+      Struct.pick(fields, keys as readonly (keyof Fields)[]) as Pick<
+        Fields,
+        Keys[number]
+      >,
+  );
+
+/**
+ * Returns a new `Schema.Struct` with the named `keys` of `schema` removed.
+ *
+ * The complement of {@link pick}, restoring the v3 ergonomics of
+ * `mySchema.omit("a")` that v4 dropped from `Schema.Struct` instances. Every
+ * surviving field keeps its original schema, including any refinements.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * const Source = Schema.Struct({
+ *   a: Schema.Number,
+ *   b: Schema.String,
+ *   c: Schema.Boolean,
+ * })
+ *
+ * const Omitted = SchemaX.omit(Source, "c")
+ *
+ * const decoded = Effect.runSync(
+ *   Schema.decodeEffect(Omitted)({ a: 1, b: "hi" }),
+ * )
+ * assert.deepStrictEqual(decoded, { a: 1, b: "hi" })
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const omit = <
+  const Fields extends Schema.Struct.Fields,
+  const Keys extends readonly (keyof Fields & string)[],
+>(
+  schema: Schema.Struct<Fields>,
+  ...keys: Keys
+): Schema.Struct<Omit<Fields, Keys[number]>> =>
+  schema.mapFields(
+    (fields) =>
+      Struct.omit(fields, keys as readonly (keyof Fields)[]) as Omit<
+        Fields,
+        Keys[number]
+      >,
+  );
+
+/**
+ * Returns a new `Schema.Struct` in which every field of `schema` is made
+ * optional.
+ *
+ * Restores the v3 `Schema.partial(mySchema)` behaviour that v4 removed, by
+ * wrapping each field in `Schema.optional`. A decoded value may therefore omit
+ * any field; fields that *are* present still have to satisfy their original
+ * schema, refinements included.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * const Source = Schema.Struct({ a: Schema.Number, b: Schema.String })
+ * const Partial = SchemaX.partial(Source)
+ *
+ * // All fields may be absent
+ * assert.deepStrictEqual(Effect.runSync(Schema.decodeEffect(Partial)({})), {})
+ *
+ * // A present subset still decodes
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Schema.decodeEffect(Partial)({ a: 1 })),
+ *   { a: 1 },
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const partial = <Fields extends Schema.Struct.Fields>(
+  schema: Schema.Struct<Fields>,
+): Schema.Struct<{ [K in keyof Fields]: Schema.optional<Fields[K]> }> =>
+  schema.mapFields((fields) => {
+    const result: { [K in keyof Fields]?: Schema.optional<Fields[K]> } = {};
+    for (const key of Object.keys(fields) as (keyof Fields)[]) {
+      result[key] = Schema.optional(fields[key]);
+    }
+    return result as { [K in keyof Fields]: Schema.optional<Fields[K]> };
+  });
+
+/**
+ * Returns a new `Schema.Struct` containing only the named `keys` of `schema`,
+ * with every picked field made optional.
+ *
+ * Equivalent to `partial(pick(schema, ...keys))`, but reads more directly for
+ * the common "partial update over a subset of fields" pattern: select the
+ * mutable fields of an entity, then allow any of them to be omitted in the
+ * update payload. Composes {@link pick} and {@link partial} in one call.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { SchemaX } from "@nunofyobiz/effect-extras"
+ *
+ * const Source = Schema.Struct({
+ *   a: Schema.Number,
+ *   b: Schema.String,
+ *   c: Schema.Boolean,
+ * })
+ *
+ * const Update = SchemaX.pickPartial(Source, "a", "b")
+ *
+ * // Only picked fields are known, and each may be omitted
+ * assert.deepStrictEqual(Effect.runSync(Schema.decodeEffect(Update)({})), {})
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Schema.decodeEffect(Update)({ a: 1 })),
+ *   { a: 1 },
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const pickPartial = <
+  const Fields extends Schema.Struct.Fields,
+  const Keys extends readonly (keyof Fields & string)[],
+>(
+  schema: Schema.Struct<Fields>,
+  ...keys: Keys
+): Schema.Struct<{ [K in Keys[number]]: Schema.optional<Fields[K]> }> =>
+  partial(pick(schema, ...keys));

package/src/SchemaX/index.ts

@@ -0,0 +1 @@
+export * as SchemaX from "./SchemaX";

package/src/SetX/SetX.ts

@@ -0,0 +1,160 @@
+/**
+ * Generic, framework-agnostic extensions for working with `Set`.
+ *
+ * @since 0.0.0
+ */
+import { dual } from "effect/Function";
+
+/**
+ * Runs a mutating function against a copy of `set`, leaving the original
+ * untouched, and returns the mutated copy.
+ *
+ * Use it to reuse imperative `Set` mutation code (`.add`, `.delete`) without
+ * sacrificing immutability: the callback may freely mutate the set it receives
+ * because it operates on a fresh clone. Supports both data-first and data-last
+ * (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * const original = new Set(["a", "b"])
+ *
+ * const result = pipe(
+ *   original,
+ *   SetX.safelyMutate((set) => {
+ *     set.delete("a")
+ *     return set.add("c")
+ *   })
+ * )
+ *
+ * assert.deepStrictEqual(result, new Set(["b", "c"]))
+ * // The original is left intact
+ * assert.deepStrictEqual(original, new Set(["a", "b"]))
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const safelyMutate = dual<
+  <A>(mutate: (set: Set<A>) => Set<A>) => (set: Set<A>) => Set<A>,
+  <A>(set: Set<A>, mutate: (set: Set<A>) => Set<A>) => Set<A>
+>(2, <A>(set: Set<A>, mutate: (set: Set<A>) => Set<A>): Set<A> => {
+  const copy = new Set(set);
+  return mutate(copy);
+});
+
+/**
+ * Returns a new `Set` with `value` added, leaving the input set unchanged.
+ *
+ * When `value` is already present the input set is returned as-is (no copy),
+ * making repeated adds of existing members allocation-free. Supports both
+ * data-first and data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — adds a new element into a fresh set
+ * assert.deepStrictEqual(
+ *   SetX.add(new Set(["a", "b"]), "c"),
+ *   new Set(["a", "b", "c"])
+ * )
+ *
+ * // Data-last — existing element leaves the set unchanged
+ * assert.deepStrictEqual(
+ *   pipe(new Set(["a", "b"]), SetX.add("b")),
+ *   new Set(["a", "b"])
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const add = dual<
+  <A>(value: A) => (set: Set<A>) => Set<A>,
+  <A>(set: Set<A>, value: A) => Set<A>
+>(
+  2,
+  <A>(set: Set<A>, value: A): Set<A> =>
+    set.has(value) ? set : new Set(set).add(value),
+);
+
+/**
+ * Returns a new `Set` with `value` removed, leaving the input set unchanged.
+ *
+ * When `value` is absent the input set is returned as-is (no copy). Supports both
+ * data-first and data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — removes an existing element into a fresh set
+ * assert.deepStrictEqual(
+ *   SetX.remove(new Set(["a", "b", "c"]), "c"),
+ *   new Set(["a", "b"])
+ * )
+ *
+ * // Data-last — absent element leaves the set unchanged
+ * assert.deepStrictEqual(
+ *   pipe(new Set(["a", "b"]), SetX.remove("z")),
+ *   new Set(["a", "b"])
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const remove = dual<
+  <A>(value: A) => (set: Set<A>) => Set<A>,
+  <A>(set: Set<A>, value: A) => Set<A>
+>(2, <A>(set: Set<A>, value: A): Set<A> => {
+  if (set.has(value)) {
+    const newSet = new Set(set);
+    newSet.delete(value);
+    return newSet;
+  }
+  return set;
+});
+
+/**
+ * Returns a new `Set` with `value` added if it was absent or removed if it was
+ * present, leaving the input set unchanged.
+ *
+ * Use it for membership toggles (selection state, feature flags by key) where a
+ * value's presence should flip on each call. Supports both data-first and
+ * data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — absent value gets added
+ * assert.deepStrictEqual(
+ *   SetX.toggle(new Set(["a", "b"]), "c"),
+ *   new Set(["a", "b", "c"])
+ * )
+ *
+ * // Data-last — present value gets removed
+ * assert.deepStrictEqual(
+ *   pipe(new Set(["a", "b", "c"]), SetX.toggle("b")),
+ *   new Set(["a", "c"])
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const toggle = dual<
+  <A>(value: A) => (set: Set<A>) => Set<A>,
+  <A>(set: Set<A>, value: A) => Set<A>
+>(
+  2,
+  <A>(set: Set<A>, value: A): Set<A> =>
+    set.has(value) ? remove(set, value) : add(set, value),
+);

package/src/SetX/index.ts

@@ -0,0 +1 @@
+export * as SetX from "./SetX";

package/src/StringX/StringX.ts

@@ -0,0 +1,97 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `String` module.
+ *
+ * @since 0.0.0
+ */
+import { dual } from "effect/Function";
+
+/**
+ * Prepends `start` to `string_`.
+ *
+ * v4's `String` module has no native `prepend` (only `concat`), so this fills
+ * the gap as a pipeable helper.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(StringX.prepend("world", "hello "), "hello world")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("world", StringX.prepend("hello ")), "hello world")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const prepend = dual<
+  (start: string) => (string_: string) => string,
+  (string_: string, start: string) => string
+>(2, (string_: string, start: string): string => `${start}${string_}`);
+
+/**
+ * Wraps `string_` between `start` and `end`.
+ *
+ * No v4 native equivalent — handy for quoting, bracketing, or fencing a value.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(StringX.surround("value", "[", "]"), "[value]")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("value", StringX.surround("(", ")")), "(value)")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const surround = dual<
+  (start: string, end: string) => (string_: string) => string,
+  (string_: string, start: string, end: string) => string
+>(
+  3,
+  (string_: string, start: string, end: string): string =>
+    `${start}${string_}${end}`,
+);
+
+/**
+ * Prepends `start` to `string_` unless `string_` already starts with it.
+ *
+ * Idempotent: applying it to an already-prefixed string is a no-op, so
+ * `ensurePrepend("foofoo", "foo")` stays `"foofoo"` rather than gaining a
+ * second `"foo"`.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first — adds the prefix when missing
+ * assert.deepStrictEqual(StringX.ensurePrepend("bar", "foo"), "foobar")
+ *
+ * // idempotent — already prefixed, returned unchanged
+ * assert.deepStrictEqual(StringX.ensurePrepend("foobar", "foo"), "foobar")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("bar", StringX.ensurePrepend("foo")), "foobar")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const ensurePrepend = dual<
+  (start: string) => (string_: string) => string,
+  (string_: string, start: string) => string
+>(2, (string_: string, start: string): string => {
+  if (string_.startsWith(start)) {
+    return string_;
+  }
+
+  return `${start}${string_}`;
+});

package/src/StringX/index.ts

@@ -0,0 +1 @@
+export * as StringX from "./StringX";