Skip to main content Link Search Menu Expand Document (external link)

StructX overview

Generic, framework-agnostic extensions to Effect’s Struct module.

Added in v0.0.0


Table of contents


constructors

defined

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.

Signature

export declare const defined: <const K extends string, V>(
  name: K,
  value: V | undefined
) => Partial<Record<K, Exclude<V, undefined>>>

Example

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("notificationLimit", 0), { notificationLimit: 0 })

// Typical use: spread to conditionally include an optional field
const nickname: string | undefined = undefined
const profile: { displayName: string; nickname?: string; notifications?: boolean } = {
  displayName: "Ada",
  ...StructX.defined("nickname", nickname),
  ...StructX.defined("notifications", false)
}
// The unset nickname is absent, while the explicit false setting survives.
assert.deepStrictEqual(profile, { displayName: "Ada", notifications: false })

Added in v0.0.0

pickSome

Looks up key in a record of Option values and returns a singleton record when the value is Some, or {} when the key is absent or its value is None.

Combines Record.get + Option.flatten + a singleton builder in one call — ideal for spreading an optional field out of a lookup table into an object literal under exactOptionalPropertyTypes: true. By default the output key matches the lookup key; pass renameKeyTo to emit the value under a different name. As with {@link some}, nullish and falsy Some payloads are preserved.

Signature

export declare function pickSome<const K extends string, V>(
  record: Record<K, Option.Option<V>>,
  key: K
): Partial<Record<K, V>>
export declare function pickSome<const K1 extends string, V, const K2 extends string>(
  record: Record<K1, Option.Option<V>>,
  key: K1,
  renameKeyTo: K2
): Partial<Record<K2, V>>

Example

import { Option } from "effect"
import { StructX } from "@nunofyobiz/effect-extras"

const lookup = {
  displayName: Option.some("Ada"),
  nickname: Option.none<string>()
}

// Some → singleton record under the same key
assert.deepStrictEqual(StructX.pickSome(lookup, "displayName"), { displayName: "Ada" })

// None → property omitted entirely
assert.deepStrictEqual(StructX.pickSome(lookup, "nickname"), {})

// Use the saved display name as the profile's public name.
assert.deepStrictEqual(StructX.pickSome(lookup, "displayName", "name"), { name: "Ada" })

// Some(undefined) keeps an own nickname property rather than omitting it.
const profile = StructX.pickSome({ nickname: Option.some(undefined) }, "nickname")
assert.deepStrictEqual(profile, { nickname: undefined })
assert.strictEqual(Object.hasOwn(profile, "nickname"), true)

Added in v0.0.0

some

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. A Some payload is preserved even when it is nullish or falsy: Some(undefined) creates an own property containing undefined.

Signature

export declare const some: <const K extends string, V>(name: K, value: Option.Option<V>) => Partial<Record<K, V>>

Example

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()), {})

// An explicitly supplied nickname is present even when its payload is undefined.
const profile = StructX.some("nickname", Option.some(undefined))
assert.deepStrictEqual(profile, { nickname: undefined })
assert.strictEqual(Object.hasOwn(profile, "nickname"), true)

Added in v0.0.0

truthy

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, -0, 0n, "", NaN), and narrows the value type accordingly. Use it to spread a field only when it carries a meaningful, non-falsy value.

Signature

export declare const truthy: <const K extends string, V>(
  name: K,
  value: V
) => Partial<Record<K, Exclude<NonNullable<V>, false | 0 | "">>>

Example

import { StructX } from "@nunofyobiz/effect-extras"

// Include a populated profile name, but omit a blank nickname.
assert.deepStrictEqual(StructX.truthy("name", "Ada"), { name: "Ada" })

// Falsy values → property omitted entirely
assert.deepStrictEqual(StructX.truthy("nickname", ""), {})
// Zero and false also disappear; use defined to preserve those settings.
assert.deepStrictEqual(StructX.truthy("notificationLimit", 0), {})
assert.deepStrictEqual(StructX.truthy("notifications", false), {})
assert.deepStrictEqual(StructX.defined("notifications", false), { notifications: false })

Added in v0.0.0

filtering

filterDefined

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”. Only own enumerable string properties are considered; inherited, non-enumerable, and symbol properties are excluded.

Signature

export declare const filterDefined: <R extends Record<string, unknown>>(
  record: R
) => Partial<{ [P in keyof R]: Exclude<R[P], undefined> }>

Example

import { StructX } from "@nunofyobiz/effect-extras"

// Leave the untouched theme out of the update; explicitly clear the avatar
// and keep the disabled notifications and zero notification limit.
assert.deepStrictEqual(
  StructX.filterDefined({ theme: undefined, avatar: null, notifications: false, notificationLimit: 0 }),
  { avatar: null, notifications: false, notificationLimit: 0 }
)

Added in v0.0.0

models

PartialTransform (type alias)

Describes the shape of a per-field transformation over an object O: a record T whose values are functions taking the corresponding field of O.

Used to type the “evolve” pattern, where each provided key maps to a function that receives that field’s current value. Copied from Effect’s internal Struct.evolve() type, which is not exported — it would be better to use theirs directly if it ever becomes public.

Signature

export type PartialTransform<O, T> = {
  [K in keyof T]: T[K] extends (a: O[K & keyof O]) => unknown ? T[K] : (a: O[K & keyof O]) => unknown
}

Example

import { Struct } from "effect"
import { StructX } from "@nunofyobiz/effect-extras"

type Profile = { displayName: string; notifications: boolean }
type Transform = StructX.PartialTransform<Profile, { displayName: (name: string) => string }>
const transform: Transform = { displayName: (name) => name.trim() }
const profile: Profile = { displayName: " Ada ", notifications: false }

// Trim the display name while leaving the other profile fields unchanged.
assert.deepStrictEqual(Struct.evolve(profile, transform), {
  displayName: "Ada",
  notifications: false
})

Added in v0.0.0

refinements

hasNotNullableProperty

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.

Signature

export declare const hasNotNullableProperty: (<T, K extends keyof T>(
  key: K
) => (object: T) => object is T & Record<K, NonNullable<T[K]>>) &
  (<T, K extends keyof T>(object: T, key: K) => object is T & Record<K, NonNullable<T[K]>>)

Example

import { Array, pipe } from "effect"
import { StructX } from "@nunofyobiz/effect-extras"

type Profile = { displayName: string | null | undefined }
const profiles: Profile[] = [{ displayName: "Ada" }, { displayName: null }, { displayName: undefined }]
// Keep profiles with a name; the narrowed string is safe to uppercase.
const names = pipe(
  profiles,
  Array.filter(StructX.hasNotNullableProperty<Profile, "displayName">("displayName")),
  Array.map((profile) => profile.displayName.toUpperCase())
)
assert.deepStrictEqual(names, ["ADA"])
assert.strictEqual(StructX.hasNotNullableProperty(profiles[0], "displayName"), true)

Added in v0.0.0