@nunofyobiz/effect-extras 2.0.0 → 2.1.0

package/dist/RecordX.js

@@ -0,0 +1,326 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Record` module.
+ *
+ * @since 0.0.0
+ */
+import { Array, Option, Predicate, Record, pipe } from "effect";
+import { dual } from "effect/Function";
+import * as ArrayX from "./ArrayX.js";
+/**
+ * Returns `true` when `record` has at least one entry, narrowing it to a
+ * known-non-empty `Record`.
+ *
+ * The negation of `Record.isEmptyRecord`, packaged as a type guard so it reads
+ * naturally at call sites that want to branch on "this record has something in
+ * it" without a manual `!Record.isEmptyRecord(...)`.
+ *
+ * @example
+ * ```ts
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(RecordX.isNonEmptyRecord({ a: 1 }), true)
+ * assert.deepStrictEqual(RecordX.isNonEmptyRecord({}), false)
+ * ```
+ *
+ * @category guards
+ * @since 0.0.0
+ */
+export const isNonEmptyRecord = record => pipe(record, Predicate.not(Record.isEmptyRecord));
+/**
+ * Modifies the value at `key` in `self` with `f`, leaving the record unchanged
+ * if the key doesn't exist.
+ *
+ * v4's `Record.modify` returns `Option<Record>` — `None` when the key is
+ * absent. This helper picks the "do nothing if absent" semantics that v3's
+ * `Record.modify` had implicitly, and that most call sites assume. The modifier
+ * is never invoked when the key is missing.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   RecordX.modifyIfExists({ a: 1, b: 2 }, "b", (n) => n * 10),
+ *   { a: 1, b: 20 },
+ * )
+ *
+ * // a missing key leaves the record untouched
+ * const counts: Record<string, number> = { a: 1, b: 2 }
+ * assert.deepStrictEqual(
+ *   RecordX.modifyIfExists(counts, "missing", (n) => n + 1),
+ *   { a: 1, b: 2 },
+ * )
+ *
+ * // data-last (pipeable)
+ * assert.deepStrictEqual(
+ *   pipe({ a: 1, b: 2 }, RecordX.modifyIfExists("a", (n) => n * 10)),
+ *   { a: 10, b: 2 },
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const modifyIfExists = /*#__PURE__*/dual(3, (self, key, f) => pipe(Record.modify(self, key, f), Option.getOrElse(() => self)));
+/**
+ * Returns the smallest value of `record` (per `order`) that matches
+ * `predicate`, narrowed to the refined type `B`, or `Option.none()` if none
+ * match.
+ *
+ * The `Record` counterpart of `ArrayX.takeFirstWhere`: it considers only the
+ * record's values, keeps those satisfying `predicate`, and returns the minimum
+ * of them by `order`. Keys are ignored entirely.
+ *
+ * @example
+ * ```ts
+ * import { Option, Order, pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * const isEven = (n: number): n is number => n % 2 === 0
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   RecordX.takeFirstWhere({ a: 3, b: 4, c: 2 }, isEven, Order.Number),
+ *   Option.some(2),
+ * )
+ *
+ * // data-last (pipeable); no even values yields None
+ * assert.deepStrictEqual(
+ *   pipe({ a: 1, b: 3 }, RecordX.takeFirstWhere(isEven, Order.Number)),
+ *   Option.none(),
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const takeFirstWhere = /*#__PURE__*/dual(3, (record, predicate, order) => ArrayX.takeFirstWhere(Record.values(record), predicate, order));
+/**
+ * Returns the largest value of `record` (per `order`) that matches `predicate`,
+ * narrowed to the refined type `B`, or `Option.none()` if none match.
+ *
+ * The mirror of {@link takeFirstWhere}: it considers only the record's values,
+ * keeps those satisfying `predicate`, and returns the maximum of them by
+ * `order`. Keys are ignored entirely.
+ *
+ * @example
+ * ```ts
+ * import { Option, Order, pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * const isEven = (n: number): n is number => n % 2 === 0
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   RecordX.takeLastWhere({ a: 3, b: 4, c: 2 }, isEven, Order.Number),
+ *   Option.some(4),
+ * )
+ *
+ * // data-last (pipeable); no even values yields None
+ * assert.deepStrictEqual(
+ *   pipe({ a: 1, b: 3 }, RecordX.takeLastWhere(isEven, Order.Number)),
+ *   Option.none(),
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const takeLastWhere = /*#__PURE__*/dual(3, (record, predicate, order) => ArrayX.takeLastWhere(Record.values(record), predicate, order));
+/**
+ * Returns the largest value of `record` according to `order`, wrapped in an
+ * `Option` so empty records are handled safely.
+ *
+ * Sorts the record's values by `order` and takes the last one, yielding
+ * `Option.none()` when the record is empty and `Option.some(max)` otherwise.
+ * Keys are ignored — only values participate in the ordering.
+ *
+ * @example
+ * ```ts
+ * import { Option, Order, pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   RecordX.takeLast({ a: 3, b: 5, c: 1 }, Order.Number),
+ *   Option.some(5),
+ * )
+ *
+ * // data-last (pipeable); empty record yields None
+ * assert.deepStrictEqual(
+ *   pipe({}, RecordX.takeLast(Order.Number)),
+ *   Option.none(),
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const takeLast = /*#__PURE__*/dual(2, (record, order) => pipe(Record.values(record), Array.sort(order), Array.last));
+/**
+ * Re-types the keys of a `Record` to a different key type `K2` without touching
+ * the runtime value.
+ *
+ * A purely type-level reinterpretation: the record is returned as-is, but the
+ * compiler now treats its keys as `K2` instead of the inferred `K1`. Use it at a
+ * boundary where you know the keys conform to a narrower branded or literal key
+ * type that TypeScript can't infer from the value alone. It performs no
+ * validation — the caller is responsible for the keys actually matching `K2`.
+ *
+ * @example
+ * ```ts
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * type UserId = string & { readonly _brand: "UserId" }
+ *
+ * const byId: Record<string, number> = { u1: 10, u2: 20 }
+ * const branded = RecordX.keysAs<UserId>()(byId)
+ *
+ * // Same runtime value, keys now seen as `UserId`
+ * assert.deepStrictEqual(branded, { u1: 10, u2: 20 })
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const keysAs = () => record => record;
+/**
+ * Returns the value at `key` in `record`, throwing an `Error` if the key is
+ * absent.
+ *
+ * The unsafe, get-or-explode counterpart to `Record.get` (which returns an
+ * `Option`). The thrown error names the missing key and lists the record's
+ * existing keys to aid debugging. Reach for {@link getOrThrowWith} when you need
+ * a custom error; prefer `Record.get` whenever absence is a real possibility.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * const record: Record<string, number> = { a: 1, b: 2 }
+ *
+ * // data-first
+ * assert.deepStrictEqual(RecordX.getOrThrow(record, "a"), 1)
+ *
+ * // data-last (pipeable)
+ * assert.deepStrictEqual(pipe(record, RecordX.getOrThrow("b")), 2)
+ *
+ * // missing key throws
+ * assert.throws(() => RecordX.getOrThrow(record, "missing"))
+ * ```
+ *
+ * @category unsafe
+ * @since 0.0.0
+ */
+export const getOrThrow = /*#__PURE__*/dual(2, (record, key) => getOrThrowWith(record, key, key => new Error(`Key ${String(key)} not found in record\nExisting keys=${String(Record.keys(record))}`)));
+/**
+ * Returns the value at `key` in `record`, throwing the result of `onNone(key)`
+ * if the key is absent.
+ *
+ * Like {@link getOrThrow}, but lets the caller supply the thrown value (an
+ * `Error`, a string, or any custom failure) computed from the missing key. Use
+ * it when the default "key not found" message isn't descriptive enough for the
+ * call site.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * const record: Record<string, number> = { a: 1 }
+ * const onNone = (key: string) => new Error(`no ${key}`)
+ *
+ * // data-first
+ * assert.deepStrictEqual(RecordX.getOrThrowWith(record, "a", onNone), 1)
+ *
+ * // data-last (pipeable)
+ * assert.deepStrictEqual(pipe(record, RecordX.getOrThrowWith("a", onNone)), 1)
+ *
+ * // missing key throws the custom error
+ * assert.throws(() => RecordX.getOrThrowWith(record, "missing", onNone))
+ * ```
+ *
+ * @category unsafe
+ * @since 0.0.0
+ */
+export const getOrThrowWith = /*#__PURE__*/dual(3, (record, key, onNone) => Record.get(record, key).pipe(Option.getOrThrowWith(() => onNone(key))));
+/**
+ * Inserts or updates the value at `key`, deriving the new value from the current
+ * one via `upsert`.
+ *
+ * The `upsert` function receives an `Option` of the existing value —
+ * `Option.some(value)` when the key is present, `Option.none()` when it's
+ * absent — and returns the value to store. This unifies "insert if missing" and
+ * "update if present" into a single pass, with `Option.match` as the natural way
+ * to handle both cases.
+ *
+ * @example
+ * ```ts
+ * import { Option, pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * const bump = Option.match({
+ *   onNone: () => 1,
+ *   onSome: (n: number) => n + 1,
+ * })
+ *
+ * // data-first: updates an existing entry
+ * assert.deepStrictEqual(RecordX.upsert({ a: 1 }, "a", bump), { a: 2 })
+ *
+ * // data-last (pipeable): inserts a missing entry
+ * const counts: Record<string, number> = { a: 1 }
+ * assert.deepStrictEqual(pipe(counts, RecordX.upsert("b", bump)), {
+ *   a: 1,
+ *   b: 1,
+ * })
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const upsert = /*#__PURE__*/dual(3, (record, key, upsert) => {
+  const existingValue = Record.get(record, key);
+  const updatedValue = upsert(existingValue);
+  return Record.set(record, key, updatedValue);
+});
+/**
+ * Indexes an iterable of values into a `Record`, keying each value by the result
+ * of `identify`.
+ *
+ * Builds a lookup table from a collection: every value is stored under the key
+ * `identify(value)`. When two values produce the same key the later one wins, so
+ * the result holds the last value seen per key. Useful for turning a list of
+ * records into a by-id map.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * const items = [
+ *   { id: "a", n: 1 },
+ *   { id: "b", n: 2 },
+ *   { id: "a", n: 3 }, // wins over the earlier "a"
+ * ]
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   RecordX.collectBy(items, (item) => item.id),
+ *   { a: { id: "a", n: 3 }, b: { id: "b", n: 2 } },
+ * )
+ *
+ * // data-last (pipeable)
+ * assert.deepStrictEqual(
+ *   pipe(items, RecordX.collectBy((item) => item.id)),
+ *   { a: { id: "a", n: 3 }, b: { id: "b", n: 2 } },
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const collectBy = /*#__PURE__*/dual(2, (values, identify) => Array.reduce(values, {}, (accumulator, value) => Record.set(accumulator, identify(value), value)));
+//# sourceMappingURL=RecordX.js.map

package/dist/RecordX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordX.js","names":["Array","Option","Predicate","Record","pipe","dual","ArrayX","isNonEmptyRecord","record","not","isEmptyRecord","modifyIfExists","self","key","f","modify","getOrElse","takeFirstWhere","predicate","order","values","takeLastWhere","takeLast","sort","last","keysAs","getOrThrow","getOrThrowWith","Error","String","keys","onNone","get","upsert","existingValue","updatedValue","set","collectBy","identify","reduce","accumulator","value"],"sources":["../src/RecordX.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/ResultX.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Result` module.
+ *
+ * @since 0.0.0
+ */
+import { Option, Result } from "effect";
+/**
+ * Lifts an `Option` into a `Result` with a `void` failure: `Some(value)` becomes
+ * `Result.succeed(value)` and `None` becomes `Result.failVoid`.
+ *
+ * Useful in v4 where `Array.filterMap` and `Record.filterMap` expect
+ * `Result`-returning predicates (a `Success` keeps the value, a `Failure` drops
+ * it); in v3 those APIs accepted `Option`-returning predicates directly:
+ *
+ * ```ts
+ * import { Array } from "effect"
+ * import { ResultX } from "@nunofyobiz/effect-extras"
+ *
+ * declare const items: ReadonlyArray<number>
+ * declare const maybeTransform: (item: number) => import("effect").Option.Option<string>
+ *
+ * // v3: Array.filterMap(items, (item) => maybeTransform(item))
+ * // v4:
+ * Array.filterMap(items, (item) => ResultX.fromOption(maybeTransform(item)))
+ * ```
+ *
+ * Effect ships `Result.fromOption(option, onNone)` which requires a non-`void`
+ * failure value; this helper specializes to the common "drop the item, no error
+ * needed" case used by `filterMap`.
+ *
+ * @example
+ * ```ts
+ * import { Option, Result } from "effect"
+ * import { ResultX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   ResultX.fromOption(Option.some(1)),
+ *   Result.succeed(1),
+ * )
+ * assert.deepStrictEqual(
+ *   ResultX.fromOption(Option.none<number>()),
+ *   Result.failVoid,
+ * )
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export declare const fromOption: <A>(option: Option.Option<A>) => Result.Result<A, void>;
+//# sourceMappingURL=ResultX.d.ts.map

package/dist/ResultX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResultX.d.ts","sourceRoot":"","sources":["../src/ResultX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAC1B,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KACvB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CACgD,CAAC"}

package/dist/ResultX.js

@@ -0,0 +1,50 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Result` module.
+ *
+ * @since 0.0.0
+ */
+import { Option, Result } from "effect";
+/**
+ * Lifts an `Option` into a `Result` with a `void` failure: `Some(value)` becomes
+ * `Result.succeed(value)` and `None` becomes `Result.failVoid`.
+ *
+ * Useful in v4 where `Array.filterMap` and `Record.filterMap` expect
+ * `Result`-returning predicates (a `Success` keeps the value, a `Failure` drops
+ * it); in v3 those APIs accepted `Option`-returning predicates directly:
+ *
+ * ```ts
+ * import { Array } from "effect"
+ * import { ResultX } from "@nunofyobiz/effect-extras"
+ *
+ * declare const items: ReadonlyArray<number>
+ * declare const maybeTransform: (item: number) => import("effect").Option.Option<string>
+ *
+ * // v3: Array.filterMap(items, (item) => maybeTransform(item))
+ * // v4:
+ * Array.filterMap(items, (item) => ResultX.fromOption(maybeTransform(item)))
+ * ```
+ *
+ * Effect ships `Result.fromOption(option, onNone)` which requires a non-`void`
+ * failure value; this helper specializes to the common "drop the item, no error
+ * needed" case used by `filterMap`.
+ *
+ * @example
+ * ```ts
+ * import { Option, Result } from "effect"
+ * import { ResultX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   ResultX.fromOption(Option.some(1)),
+ *   Result.succeed(1),
+ * )
+ * assert.deepStrictEqual(
+ *   ResultX.fromOption(Option.none<number>()),
+ *   Result.failVoid,
+ * )
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const fromOption = option => Option.isSome(option) ? Result.succeed(option.value) : Result.failVoid;
+//# sourceMappingURL=ResultX.js.map

package/dist/ResultX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResultX.js","names":["Option","Result","fromOption","option","isSome","succeed","value","failVoid"],"sources":["../src/ResultX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,OAAO,MAAMC,UAAU,GACrBC,MAAwB,IAExBH,MAAM,CAACI,MAAM,CAACD,MAAM,CAAC,GAAGF,MAAM,CAACI,OAAO,CAACF,MAAM,CAACG,KAAK,CAAC,GAAGL,MAAM,CAACM,QAAQ","ignoreList":[]}

package/dist/SchemaX.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Schema` module.
+ *
+ * @since 0.0.0
+ */
+import { Schema } 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 declare const TrimmedNonEmptyString: Schema.decodeTo<Schema.toType<Schema.NonEmptyString>, Schema.NonEmptyString, never, never>;
+/**
+ * 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 declare const URLSafeFilePath: Schema.decodeTo<Schema.toType<Schema.decodeTo<Schema.toType<Schema.NonEmptyString>, Schema.NonEmptyString, never, never>>, Schema.decodeTo<Schema.toType<Schema.NonEmptyString>, Schema.NonEmptyString, never, never>, never, never>;
+/**
+ * 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 declare const nonNegativeBigInt: <S extends Schema.Schema<bigint>>(schema: S) => Schema.decodeTo<Schema.toType<S>, S, never, never>;
+/**
+ * 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"];
+/**
+ * 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 declare 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]>>;
+/**
+ * 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 declare 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]>>;
+/**
+ * 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 declare const partial: <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) => Schema.Struct<{ [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 declare 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]>; }>;
+//# sourceMappingURL=SchemaX.d.ts.map