schema-expert

Related skills: schema-composition, pattern-matching

<schema-mind>

<schema>
Schema[A, I, R] := Transformation[I -> A, R]

<composition>
compose :: Schema[B, A, R1] -> Schema[C, B, R2] -> Schema[C, A, R1 | R2]
pipe    :: Schema[A, I, R] -> Filter[A] -> Schema[A, I, R]

compose = different types (chain transformations)
pipe    = same type (add refinements)

-- Multi-step transformation
Unknown -> Boolean -> Literal(true)
compose(BooleanFromUnknown, Literal(true))

-- Sequential refinements
Number -> Int -> Positive
Number.pipe(int(), positive())
</composition>

<built-in-transformations>
numeric     := NumberFromString, BooleanFromUnknown
temporal    := DateFromString, DateTimeUtcFromSelf
structural  := NonEmptyArray, NonEmptyString
constraint  := Positive, Negative, NonNegative, Int, Finite
string      := Trimmed, Lowercased, Uppercased
boolean     := Not (transformation, not combinator)

-- Not is boolean -> boolean transformation
compose(BooleanFromUnknown, Not)
</built-in-transformations>

<filters>
numeric := greaterThan(n), lessThan(n), between(min, max)
string  := pattern(regex), includes(s), minLength(n), maxLength(n)
array   := minItems(n), maxItems(n), itemsCount(n)
</filters>

<nullability>
NullOr(schema)    := A | null
UndefinedOr(schema) := A | undefined
NullishOr(schema) := A | null | undefined
</nullability>
</schema>

<tagged-enum>
Data.TaggedEnum[Variants] := Sum[Tag1 D1 | Tag2 D2 | ... | Tagn Dn]

<construction>
type State = Data.TaggedEnum<{
  Loading: {}
  Ready: { value: A }
  Failed: { error: E }
}>
const State = Data.taggedEnum<State>()

-- Automatic constructors
State.Loading({})
State.Ready({ value: x })
State.Failed({ error: e })
</construction>

<pattern-matching>
$match :: State -> { Loading: () -> B, Ready: ({value}) -> B, Failed: ({error}) -> B } -> B
$match(state, {
  Loading: () => handleLoading,
  Ready: ({ value }) => handleReady(value),
  Failed: ({ error }) => handleFailed(error)
})

-- Compile-time exhaustiveness guaranteed
</pattern-matching>

<type-guards>
$is :: Tag -> State -> Boolean
$is("Ready")(state)  -- state is Ready

-- Pipeline-friendly filtering
parts.filter($is("Text"))
pipe(parts, Array.some($is("Error")))
</type-guards>
</tagged-enum>

<effect-match>
Effect.match :: E[A, Err] -> { onSuccess: A -> B, onFailure: Err -> B } -> E[B]
Effect.matchEffect :: E[A, Err] -> { onSuccess: A -> E[B], onFailure: Err -> E[B] } -> E[B]

-- Match on success/failure without Effect.either
Effect.match(myEffect, {
  onSuccess: (value) => `Got: ${value}`,
  onFailure: (error) => `Error: ${error.message}`
})
</effect-match>

<agent>
Agent :: Skills -> Context -> Problem -> E[Solution]

<laws>
knowledge-first:  forall p. act(p) requires gather(skills(p)) ^ gather(context(p))
no-assumption:    assume(k) -> invalid; ensure(k) -> valid
completeness:     solution(p) requires forall s in skills(p). invoked(s)
identity:         Agent(empty) = empty
homomorphism:     Agent(p1 . p2) = Agent(p1) . Agent(p2)
idempotence:      verified(s) -> Agent(Agent(p)) = Agent(p)
totality:         forall p. Agent(p) in {Solution, Unsolvable, NeedSkill}
adt-first:        domain-type(T) -> T := Tag1 D1 | Tag2 D2 | ... | Tagn Dn
exhaustive-match: handle(adt) -> match(adt, { Tag1: h1, Tag2: h2, ..., Tagn: hn })

-- Schema-specific laws
compose-vs-pipe:  different-types -> compose; same-type-refinement -> pipe
built-in-first:   forall transform. use(built-in(transform)) before create(custom(transform))
factory-extraction: reused(schema) -> extract(schemaFactory)
decode-direct:    flatMap(Schema.decodeUnknown(s)) over flatMap(v => decode(s)(v))
error-outside:    flatMap(decode) >> mapError over flatMap(decode >> mapError)
</laws>

<acquire>
acquire :: Problem -> E[(Skills, Context)]
acquire problem = do
  skill-needs   <- analyze(problem, "skills")
  context-needs <- analyze(problem, "context")
  adts          <- identify(discriminated-unions(problem))
  skills  <- for need in skill-needs: invoke(dispatch(need))
  context <- for need in context-needs: read/module/grep(need)
  pure(skills, context, adts)
</acquire>

<loop>
loop :: E[(), never, empty]
loop = do
  (skills, context, adts) <- acquire(problem)
  patterns <- identify(problem, context)
  for pattern in patterns:
    | needs-transformation(pattern)  -> apply(compose-vs-pipe)
    | can-use-built-in(pattern)      -> apply(built-in-first)
    | schema-reused(pattern)         -> apply(factory-extraction)
    | not exhaustive-match(pattern)  -> apply($match)
    | manual-tag-check(pattern)      -> apply($is)
    | Effect.either-pattern(pattern) -> apply(Effect.match)
  solution <- synthesize(transforms, skills, context, adts)
  verified <- verify(solution)
  emit(verified)
</loop>

<transforms>
-- Schema composition
Schema.compose(Unknown->A, A->B)  -- chain types
Schema.pipe(A, filter1, filter2)  -- refine type

-- Pattern matching
if x._tag === "A"      -> $match(x, {...})           -- pattern-match
switch(x._tag)         -> $match(x, {...})           -- exhaustive
part.filter(manual)    -> parts.filter($is("Tag"))   -- type-guard
Effect.either + check  -> Effect.match               -- effect-match

-- Schema effects
flatMap(v => decode(s)(v))     -> flatMap(decodeUnknown(s))      -- direct decode
flatMap(decode >> mapError)    -> flatMap(decode) >> mapError    -- error outside

-- Schema reuse
inline Schema.Number.pipe(...) -> const MySchema = ...; reuse    -- factory
</transforms>

<skills>
dispatch :: Need -> Skill
dispatch = \need -> case need of
  need(complex-schemas)   -> /schema-composition
  need(adt-matching)      -> /pattern-matching
  need(domain-types)      -> /domain-modeling
</skills>

<invariants>
forall output:
  compose-for-type-change
  ∧ pipe-for-refinement
  ∧ built-in-schemas-preferred
  ∧ exhaustive-pattern-matching
  ∧ no-manual-tag-checks
  ∧ $match-over-switch
  ∧ $is-over-instanceof
  ∧ error-mapping-outside-flatMap
  ∧ factories-for-reused-schemas
</invariants>
</agent>

<documentation>
<effect>
Schema is imported from effect/Schema, not @effect/schema.

```typescript
import { Schema } from "effect"
```

For comprehensive documentation, view .context/effect/.
</effect>
</documentation>

<anti-patterns>
<tag-checks>
if (part._tag === "Text") { ... }  -- invalid
StreamPart.$match(part, { ... })   -- valid
</tag-checks>

<effect-either>
-- Effect.either with manual checks
const result = yield* Effect.either(getUser("123"))
if (result._tag === "Left") { ... }  -- invalid

-- Use Effect.match instead
Effect.match(getUser("123"), {
  onSuccess: (user) => user,
  onFailure: (error) => null
})  -- valid
</effect-either>

<verbose-flatmap>
-- Invalid: error mapping inside flatMap
Effect.flatMap((value) =>
  Schema.decodeUnknown(schema)(value).pipe(
    Effect.mapError(toError)
  )
)

-- Valid: error mapping outside flatMap
Effect.flatMap(Schema.decodeUnknown(schema)),
Effect.mapError(toError)
</verbose-flatmap>
</anti-patterns>

<examples>
<compose>
Multi-step Transformation

```typescript
import { Schema } from "effect"

const TruthySchema = Schema.compose(Schema.BooleanFromUnknown, Schema.Literal(true))
const NotFromUnknown = Schema.compose(Schema.BooleanFromUnknown, Schema.Not)
```
</compose>

<pipe>
Sequential Refinements

```typescript
import { Schema } from "effect"

const PositiveInt = Schema.Number.pipe(
  Schema.int(),
  Schema.positive()
)
```
</pipe>

<factory>
Schema Factory Extraction

```typescript
import { Effect, Schema } from "effect"

const createGreaterThanSchema = (n: number) =>
  Schema.Number.pipe(Schema.greaterThan(n))

export const beGreaterThan = (n: number) =>
  <E, R>(self: Effect.Effect<number, E, R>) =>
    self.pipe(
      Effect.flatMap(Schema.decodeUnknown(createGreaterThanSchema(n))),
      Effect.mapError(toAssertionError)
    )
```
</factory>

<tagged-enum-usage>
Data.TaggedEnum with $match and $is

```typescript
import { Data, Array, pipe } from "effect"

type StreamPart = Data.TaggedEnum<{
  readonly Text: { readonly content: string }
  readonly ToolCall: { readonly name: string; readonly params: unknown }
  readonly Error: { readonly message: string }
}>

const StreamPart = Data.taggedEnum<StreamPart>()

const handle = (part: StreamPart) =>
  StreamPart.$match(part, {
    Text: ({ content }) => processText(content),
    ToolCall: ({ name, params }) => executeTool(name, params),
    Error: ({ message }) => reportError(message)
  })

const isText = StreamPart.$is("Text")
const textParts = parts.filter(isText)
const hasText = pipe(parts, Array.some(isText))
```
</tagged-enum-usage>
</examples>

</schema-mind>