Add option to preserve excess properties from S.decode, S.parse

[alex-dixon]

What is the problem this feature would solve?

The default behavior of S.parse and S.decode is to ignore excess properties. This means S.decode will select only the keys of the data that a schema specifies.

Example:

const data = S.parseSync({foo: S.string})({foo: 'ok', bar: 'ok'})
data.bar  => undefined

Sometimes, this is not desirable. This feature would allow users to opt-in to preserving excess properties at runtime for all schemas without needing to write their schemas any differently.

Users of fp-ts/io-ts migrating to Effect may benefit from having this option available as it would mirror the default behavior of io-ts's decode function, which is roughly equivalent to S.parse and S.decode in Schema.

What is the feature you are proposing to solve the problem?

ParseOptions is currently defined as:

/**
 * @category model
 * @since 1.0.0
 */
export interface ParseOptions {
  /** default "first" */
  readonly errors?: "first" | "all"
  /** default "ignore" */
  readonly onExcessProperty?: "ignore" | "error"
}

onExcessProperty could add a "preserve" option. When provided this option would alter the behavior of S.parse and S.decode such that they do not error on unknown keys or strip them at runtime.

What alternatives have you considered?

I have been trying solutions in userland since April of last year. Wrapping existing types that should have this behavior with S.extend(type, S.record(S.string, S.any)) is difficult to enforce across teams and large codebases. It has perhaps seemed obtuse when the addition is solely to force certain runtime behavior of S.parse (for example, to preserve data sent to HTTP endpoints in logs). The cost of this can be significant (data loss, confusion between clients and devs about what is being sent or not).