effect-app 4.0.0-beta.32 → 4.0.0-beta.321

package/src/Schema/ext.ts

@@ -1,10 +1,49 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
-import { Effect, Option, pipe, Schema, type SchemaAST, SchemaGetter, SchemaIssue, SchemaTransformation, ServiceMap } from "effect"
+/**
+ * # `withConstructorDefault` policy
+ *
+ * The `withConstructorDefault` properties exported throughout this module
+ * (and from `numbers.ts`, `moreStrings.ts`, `ids.ts`) attach a default value
+ * that is **only** applied during construction — i.e. when the field is
+ * omitted from the input to a Schema constructor / `.make(...)` call.
+ *
+ * They are **NOT** applied during `decode` (JSON, database rows, RPC payloads,
+ * etc.). Decoding a payload with a missing field will still fail with a parse
+ * error, exactly as if the default were not present.
+ *
+ * Concretely this means `withConstructorDefault` MUST NOT be relied on as a
+ * just-in-time migration mechanism for database fields. If a stored record is
+ * missing a newly added field, the constructor default will not fill it in on
+ * read — decoding will fail.
+ *
+ * ## Don't reach for `withDecodingDefault*` either
+ *
+ * The sibling `withDecodingDefaultType` (and `withDecodingDefault`) extensions
+ * exist, but they are discouraged for migrating persisted data. A missing
+ * field in a stored record is just as likely to be data corruption as it is
+ * an old-shape document; silently substituting a default hides the problem
+ * and can poison downstream aggregates.
+ *
+ * Prefer an **explicit, preferably versioned** migration of database data
+ * (a schema-version field, a one-shot backfill, or a transform on read that
+ * is gated on an explicit version marker) over shoving missing fields under
+ * the rug with a decode-time default.
+ */
+import * as Config from "effect/Config"
+import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
+import * as Function from "effect/Function"
+import * as Option from "effect/Option"
 import * as S from "effect/Schema"
-import { type NonEmptyReadonlyArray } from "../Array.js"
-import { extendM, typedKeysOf } from "../utils.js"
-import { type AST } from "./schema.js"
+import * as SchemaIssue from "effect/SchemaIssue"
+import * as SchemaTransformation from "effect/SchemaTransformation"
+import * as Struct from "effect/Struct"
+import { type NonEmptyReadonlyArray } from "../Array.ts"
+import * as Context from "../Context.ts"
+import * as SchemaAST from "../SchemaAST.ts"
+import { extendM, typedKeysOf } from "../utils.ts"
+import { type AST } from "./schema.ts"
 
 type ProvidedCodec<Self extends S.Top, R> = S.Codec<
   Self["Type"],
@@ -13,131 +52,410 @@ type ProvidedCodec<Self extends S.Top, R> = S.Codec<
   Exclude<Self["EncodingServices"], R>
 >
 
-// TODO: v4 migration — withConstructorDefault signature changed, propertySignature removed
-// Constraint relaxed from `Self extends S.Top & S.WithoutConstructorDefault` to `Self extends S.Top`
-// because `.pipe()` widens the schema type to `Top` which doesn't satisfy `WithoutConstructorDefault`.
-// The narrowing assertions below are safe — we're asserting "this schema hasn't had a default applied yet".
-export const withDefaultConstructor = <A>(
-  makeDefault: () => NoInfer<A>
-) =>
-<Self extends S.Top>(self: Self): S.withConstructorDefault<Self & S.WithoutConstructorDefault> => {
-  type Narrowed = Self & S.WithoutConstructorDefault
-  return S.withConstructorDefault<Narrowed>(
-    () => Option.some(makeDefault() as Narrowed["~type.make.in"])
-  )(self as Narrowed)
-}
-
-// TODO: v4 migration - Date is no longer by default encoded to string.
-const DateFromString = Schema.Date.pipe(
-  Schema.encodeTo(Schema.String, {
-    decode: SchemaGetter.Date(),
-    encode: SchemaGetter.transform((_) => _.toISOString())
-  })
+const concurrencySetting = Effect.runSync(
+  Config
+    .Literal("unbounded", "SCHEMA_CONCURRENCY")
+    .pipe(Config.orElse(() => Config.Number("SCHEMA_CONCURRENCY")), Config.option)
 )
 
+export const DefaultParseOptions: SchemaAST.ParseOptions = {
+  concurrency: Option.getOrElse(concurrencySetting, () => "unbounded" as const)
+}
+
 /**
- * Like the default Schema `Date` but from String with `withDefault` => now
+ * Parse-options annotation used on schema constructors for decode paths where callers
+ * cannot currently pass parse options (notably some RPC / HttpApi integration paths).
+ *
+ * Keep this annotation in place so those framework-managed decodes still run with
+ * unbounded concurrency by default.
  */
-export const Date = Object.assign(DateFromString, {
-  withDefault: DateFromString.pipe(withDefaultConstructor(() => new global.Date()))
+export const concurrencyUnbounded = { parseOptions: DefaultParseOptions } as const
+
+type DecodeLike = (schema: any) => (input: any, options?: SchemaAST.ParseOptions) => any
+
+export const withDefaultParseOptions = <Decode extends DecodeLike>(
+  decode: Decode,
+  defaultParseOptions: SchemaAST.ParseOptions = DefaultParseOptions
+): Decode =>
+  ((schema: any) => {
+    const run = decode(schema)
+    return (input: any, options?: SchemaAST.ParseOptions) => run(input, { ...defaultParseOptions, ...options })
+  }) as Decode
+
+const DateString = S.String.annotate({
+  identifier: "DateOrInvalid",
+  description: "an ISO 8601 date string that will be decoded as a Date (may be invalid)",
+  format: "date-time"
 })
 
 /**
- * Like the default Schema `Boolean` but with `withDefault` => false
+ * Schema type for {@link DateFromString}.
+ *
+ * @category Schemas
+ * @since 4.0.0
  */
-export const Boolean = Object.assign(S.Boolean, {
-  withDefault: S.Boolean.pipe(withDefaultConstructor(() => false))
+export interface DateFromString extends S.decodeTo<S.Date, S.String> {}
+
+/**
+ * A transformation schema that parses an ISO 8601 string into a `Date`.
+ *
+ * Decoding:
+ * - A `string` is decoded as a `Date`.
+ *
+ * Encoding:
+ * - A `Date` is encoded as a `string`.
+ *
+ * Use this when the Encoded form must be JSON (`string`). Domain models should
+ * prefer {@link Date}, whose Encoded form is `Date`; JSON stores convert via
+ * `Schema.toCodecJson`.
+ *
+ * @since 4.0.0
+ */
+export const DateFromString: DateFromString = DateString.pipe(S.decodeTo(S.Date, SchemaTransformation.dateFromString))
+
+const dateHelpers = (s: S.Date) => ({
+  /**
+   * Construction-only default `new Date()`. Applied only when the field is
+   * omitted from `.make(...)` input. NOT applied during decode — cannot be
+   * used to JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new globalThis.Date()))),
+  /**
+   * Decode-time default `new Date()`. **Discouraged for persisted data:** a
+   * missing field may be data corruption, not an old-shape document; silently
+   * substituting `new Date()` hides the problem. Prefer an explicit,
+   * preferably versioned migration over a decode-time fallback. See
+   * file-level note.
+   */
+  withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.sync(() => new globalThis.Date())))
 })
 
+/** Like the default Schema `Date` (Encoded is `Date`) with default helpers. */
+export const Date = extendM(S.Date, dateHelpers)
+
 /**
- * Like the default Schema `Number` but with `withDefault` => 0
+ * Alias of {@link Date}. Core `Schema.Date` already rejects invalid Dates.
+ *
+ * @deprecated Use {@link Date}.
  */
-export const Number = Object.assign(S.Number, { withDefault: S.Number.pipe(withDefaultConstructor(() => 0)) })
+export const DateValid = Date
+
+/** Like the default Schema `Boolean` but with default helpers. */
+export const Boolean = Object.assign(S.Boolean, {
+  /**
+   * Construction-only default `false`. Applied only when the field is
+   * omitted from `.make(...)` input. NOT applied during decode — cannot be
+   * used to JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: S.Boolean.pipe(S.withConstructorDefault(Effect.succeed(false))),
+  /**
+   * Decode-time default `false`. **Discouraged for persisted data:** a
+   * missing field may be data corruption, not an old-shape document; silently
+   * substituting `false` hides the problem. Prefer an explicit, preferably
+   * versioned migration over a decode-time fallback. See file-level note.
+   */
+  withDecodingDefaultType: S.Boolean.pipe(S.withDecodingDefaultType(Effect.succeed(false)))
+})
 
 /**
- * Like the default Schema `Literal` but with `withDefault` => literals[0]
+ * You probably want to use `Finite` instead of this. Like the default Schema
+ * `Number` but with default helpers.
  */
-export const Literal = <Literals extends NonEmptyReadonlyArray<AST.LiteralValue>>(...literals: Literals) =>
+export const Number = Object.assign(S.Number, {
+  /**
+   * Construction-only default `0`. Applied only when the field is omitted
+   * from `.make(...)` input. NOT applied during decode — cannot be used to
+   * JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: S.Number.pipe(S.withConstructorDefault(Effect.succeed(0))),
+  /**
+   * Decode-time default `0`. **Discouraged for persisted data:** a missing
+   * field may be data corruption, not an old-shape document; silently
+   * substituting `0` hides the problem. Prefer an explicit, preferably
+   * versioned migration over a decode-time fallback. See file-level note.
+   */
+  withDecodingDefaultType: S.Number.pipe(S.withDecodingDefaultType(Effect.succeed(0)))
+})
+
+/** Like the default Schema `Finite` but with default helpers. */
+export const Finite = Object.assign(S.Finite, {
+  /**
+   * Construction-only default `0`. Applied only when the field is omitted
+   * from `.make(...)` input. NOT applied during decode — cannot be used to
+   * JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: S.Finite.pipe(S.withConstructorDefault(Effect.succeed(0))),
+  /**
+   * Decode-time default `0`. **Discouraged for persisted data:** a missing
+   * field may be data corruption, not an old-shape document; silently
+   * substituting `0` hides the problem. Prefer an explicit, preferably
+   * versioned migration over a decode-time fallback. See file-level note.
+   */
+  withDecodingDefaultType: S.Finite.pipe(S.withDecodingDefaultType(Effect.succeed(0)))
+})
+
+/** Like the default Schema `Literals` but with default helpers. Default value is `literals[0]`. */
+export const Literals = <const Literals extends NonEmptyReadonlyArray<AST.LiteralValue>>(literals: Literals) =>
   pipe(
     S.Literals(literals),
     (s) =>
       Object.assign(s, {
+        /** Override the default literal value used by `withConstructorDefault` / `withDecodingDefaultType`. */
         changeDefault: <A extends Literals[number]>(a: A) => {
           return Object.assign(S.Literals(literals), {
             Default: a,
-            withDefault: s.pipe(withDefaultConstructor(() => a))
+            /**
+             * Construction-only default. Applied only when the field is
+             * omitted from `.make(...)` input. NOT applied during decode —
+             * cannot be used to JIT-migrate database fields. See file-level
+             * note.
+             */
+            withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.succeed(a))),
+            /**
+             * Decode-time default. **Discouraged for persisted data:** a
+             * missing field may be data corruption, not an old-shape
+             * document; silently substituting hides the problem. Prefer an
+             * explicit, preferably versioned migration over a decode-time
+             * fallback. See file-level note.
+             */
+            withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.succeed(a)))
           }) // todo: copy annotations from original?
         },
-        Default: literals[0] as typeof literals[0],
-        withDefault: s.pipe(withDefaultConstructor(() => literals[0]))
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- load-bearing: Object.assign widens the field type without it, breaking `expectTypeOf(l.Default).toEqualTypeOf<"a">()` in tests
+        Default: literals[0] as Literals[0],
+        /**
+         * Construction-only default `literals[0]`. Applied only when the
+         * field is omitted from `.make(...)` input. NOT applied during
+         * decode — cannot be used to JIT-migrate database fields. See
+         * file-level note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.succeed(literals[0]))),
+        /**
+         * Decode-time default `literals[0]`. **Discouraged for persisted
+         * data:** a missing field may be data corruption, not an old-shape
+         * document; silently substituting hides the problem. Prefer an
+         * explicit, preferably versioned migration over a decode-time
+         * fallback. See file-level note.
+         */
+        withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.succeed(literals[0])))
       })
   )
 
-/**
- * Like the default Schema `Array` but with `withDefault` => []
- */
+/** Like the default Schema `Array` but with default helpers. */
 export function Array<ValueSchema extends S.Top>(value: ValueSchema) {
   return pipe(
-    S.Array(value),
-    (s) => Object.assign(s, { withDefault: s.pipe(withDefaultConstructor(() => [])) })
+    S.Array(value).annotate(concurrencyUnbounded),
+    (s) =>
+      Object.assign(s, {
+        /**
+         * Construction-only default `[]`. Applied only when the field is
+         * omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => []))),
+        /**
+         * Decode-time default `[]`. **Discouraged for persisted data:** a
+         * missing field may be data corruption, not an old-shape document;
+         * silently substituting `[]` hides the problem. Prefer an explicit,
+         * preferably versioned migration over a decode-time fallback. See
+         * file-level note.
+         */
+        withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.sync(() => [])))
+      })
   )
 }
 
 /**
- * Like the default Schema `Map` but with `withDefault` => []
+ * An annotated `S.Array` of unique items that decodes to a `ReadonlySet`.
  */
-function Map_<KeySchema extends S.Top, ValueSchema extends S.Top>(input: { key: KeySchema; value: ValueSchema }) {
-  return pipe(
-    S.ReadonlyMap(input.key, input.value),
-    (s) => Object.assign(s, { withDefault: s.pipe(withDefaultConstructor(() => new global.Map())) })
+export const ReadonlySetFromArray = <ValueSchema extends S.Top>(value: ValueSchema) => {
+  const from = S
+    .Array(value)
+    .annotate({ ...concurrencyUnbounded, expected: "an array of unique items that will be decoded as a ReadonlySet" })
+  const to = S.instanceOf(Set) as S.instanceOf<ReadonlySet<ValueSchema["Type"]>>
+  const schema = from.pipe(
+    S.decodeTo(
+      to,
+      SchemaTransformation.transform({
+        decode: (arr) => new Set(arr) as ReadonlySet<ValueSchema["Type"]>,
+        encode: (set) => [...set]
+      })
+    )
   )
+  return schema
 }
 
-export { Map_ as Map }
-
 /**
- * Like the default Schema `ReadonlySet` but with `withDefault` => new Set()
+ * An annotated `S.Array` of key-value tuples that decodes to a `ReadonlyMap`.
  */
+export const ReadonlyMapFromArray = <KeySchema extends S.Top, ValueSchema extends S.Top>(pair: {
+  readonly key: KeySchema
+  readonly value: ValueSchema
+}) => {
+  const from = S
+    .Array(S.Tuple([pair.key, pair.value]))
+    .annotate({
+      ...concurrencyUnbounded,
+      expected: "an array of key-value tuples that will be decoded as a ReadonlyMap"
+    })
+  const to = S.instanceOf(Map) as S.instanceOf<
+    ReadonlyMap<KeySchema["Type"], ValueSchema["Type"]>
+  >
+  const schema = from.pipe(
+    S.decodeTo(
+      to,
+      SchemaTransformation.transform({
+        decode: (
+          arr
+        ) => new Map(arr) as ReadonlyMap<KeySchema["Type"], ValueSchema["Type"]>,
+        encode: (
+          map
+        ) => [...map.entries()] as any // fu
+      })
+    )
+  )
+  return schema
+}
+
+/** Like the default Schema `ReadonlySet` (Encoded is `Set`) with default helpers. */
 export const ReadonlySet = <ValueSchema extends S.Top>(value: ValueSchema) =>
   pipe(
     S.ReadonlySet(value),
     (s) =>
-      Object.assign(s, { withDefault: s.pipe(withDefaultConstructor(() => new Set<S.Schema.Type<ValueSchema>>())) })
+      Object.assign(s, {
+        /**
+         * Construction-only default `new Set()`. Applied only when the field
+         * is omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(
+          S.withConstructorDefault(Effect.sync(() => new Set<ValueSchema["Type"]>()))
+        ),
+        /**
+         * Decode-time default `new Set()`. **Discouraged for persisted
+         * data:** a missing field may be data corruption, not an old-shape
+         * document; silently substituting an empty set hides the problem.
+         * Prefer an explicit, preferably versioned migration over a
+         * decode-time fallback. See file-level note.
+         */
+        withDecodingDefaultType: s.pipe(
+          S.withDecodingDefaultType(Effect.sync(() => new Set<ValueSchema["Type"]>()))
+        )
+      })
   )
 
-/**
- * Like the default Schema `ReadonlyMap` but with `withDefault` => new Map()
- */
+/** Like the default Schema `ReadonlyMap` (Encoded is `Map`) with default helpers. */
 export const ReadonlyMap = <KeySchema extends S.Top, ValueSchema extends S.Top>(pair: {
   readonly key: KeySchema
   readonly value: ValueSchema
 }) =>
   pipe(
     S.ReadonlyMap(pair.key, pair.value),
-    (s) => Object.assign(s, { withDefault: s.pipe(withDefaultConstructor(() => new Map())) })
+    (s) =>
+      Object.assign(s, {
+        /**
+         * Construction-only default `new Map()`. Applied only when the field
+         * is omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new Map()))),
+        /**
+         * Decode-time default `new Map()`. **Discouraged for persisted
+         * data:** a missing field may be data corruption, not an old-shape
+         * document; silently substituting an empty map hides the problem.
+         * Prefer an explicit, preferably versioned migration over a
+         * decode-time fallback. See file-level note.
+         */
+        withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.sync(() => new Map())))
+      })
   )
 
-/**
- * Like the default Schema `NullOr` but with `withDefault` => null
- */
+/** Like the default Schema `NullOr` but with default helpers. */
 export const NullOr = <Schema extends S.Top>(self: Schema) =>
   pipe(
     S.NullOr(self),
-    (s) => Object.assign(s, { withDefault: s.pipe(withDefaultConstructor(() => null)) })
+    (s) =>
+      Object.assign(s, {
+        /**
+         * Construction-only default `null`. Applied only when the field is
+         * omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.succeed(null))),
+        /**
+         * Decode-time default `null`. **Discouraged for persisted data:** a
+         * missing field may be data corruption, not an old-shape document;
+         * silently substituting `null` hides the problem. Prefer an
+         * explicit, preferably versioned migration over a decode-time
+         * fallback. See file-level note.
+         */
+        withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.succeed(null)))
+      })
   )
 
-export const defaultDate = <Schema extends S.Top>(schema: Schema) =>
-  schema.pipe(withDefaultConstructor(() => new global.Date()))
+/**
+ * Attach a `withConstructorDefault` of `new Date()` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
+export const defaultDate = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
+  schema.pipe(S.withConstructorDefault(Effect.sync(() => new global.Date())))
 
-export const defaultBool = <Schema extends S.Top>(schema: Schema) => schema.pipe(withDefaultConstructor(() => false))
+/**
+ * Attach a `withConstructorDefault` of `false` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
+export const defaultBool = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
+  schema.pipe(S.withConstructorDefault(Effect.succeed(false)))
 
-export const defaultNullable = <Schema extends S.Top>(schema: Schema) => schema.pipe(withDefaultConstructor(() => null))
+/**
+ * Attach a `withConstructorDefault` of `null` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
+export const defaultNullable = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
+  schema.pipe(S.withConstructorDefault(Effect.succeed(null)))
 
-export const defaultArray = <Schema extends S.Top>(schema: Schema) => schema.pipe(withDefaultConstructor(() => []))
+/**
+ * Attach a `withConstructorDefault` of `[]` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
+export const defaultArray = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
+  schema.pipe(S.withConstructorDefault(Effect.sync(() => [])))
 
-export const defaultMap = <Schema extends S.Top>(schema: Schema) => schema.pipe(withDefaultConstructor(() => new Map()))
+/**
+ * Attach a `withConstructorDefault` of `new Map()` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
+export const defaultMap = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
+  schema.pipe(S.withConstructorDefault(Effect.sync(() => new Map())))
 
-export const defaultSet = <Schema extends S.Top>(schema: Schema) => schema.pipe(withDefaultConstructor(() => new Set()))
+/**
+ * Attach a `withConstructorDefault` of `new Set()` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
+export const defaultSet = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
+  schema.pipe(S.withConstructorDefault(Effect.sync(() => new Set())))
 
 export const withDefaultMake = <Self extends S.Top>(s: Self) => {
   const a = Object.assign(S.decodeSync(s as any) as WithDefaults<Self>, s)
@@ -166,9 +484,25 @@ export type WithDefaults<Self extends S.Top> = (
 // export type UnionToIntersection3<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I
 //   : never
 
+/** Union of core `Schema.Date` (Date objects) and string-encoded `DateFromString`, with default helpers. */
 export const inputDate = extendM(
-  S.Union([S.DateValid, S.Date]),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => new globalThis.Date())) })
+  S.Union([S.Date, DateFromString]),
+  (s) => ({
+    /**
+     * Construction-only default `new Date()`. Applied only when the field is
+     * omitted from `.make(...)` input. NOT applied during decode — cannot be
+     * used to JIT-migrate database fields. See file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new globalThis.Date()))),
+    /**
+     * Decode-time default `new Date()`. **Discouraged for persisted data:** a
+     * missing field may be data corruption, not an old-shape document;
+     * silently substituting `new Date()` hides the problem. Prefer an
+     * explicit, preferably versioned migration over a decode-time fallback.
+     * See file-level note.
+     */
+    withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.sync(() => new globalThis.Date())))
+  })
 )
 
 export interface UnionBrand {}
@@ -186,13 +520,81 @@ export function makeOptional<NER extends S.Struct.Fields>(
   }, {} as any)
 }
 
+// `Omit` erases the polymorphic `this` of "this-returning" methods (`annotate`, `annotateKey`,
+// `check`, `rebuild`): extracting them through a mapped type binds their `this["Rebuild"]` back to
+// the original `T`, not to this intersection. So overriding just `Rebuild` above is not enough, those
+// four methods have to be redeclared here with a concrete return type instead of `this["Rebuild"]`.
+export type DropConstructorDefault<T extends S.Top> =
+  & Omit<
+    T,
+    "~type.constructor.default" | "Rebuild" | "annotate" | "annotateKey" | "check" | "rebuild"
+  >
+  & {
+    readonly "~type.constructor.default": "no-default"
+    readonly "Rebuild": DropConstructorDefault<T>
+    annotate(annotations: S.Annotations.Bottom<T["Type"], T["~type.parameters"]>): DropConstructorDefault<T>
+    annotateKey(annotations: S.Annotations.Key<T["Type"]>): DropConstructorDefault<T>
+    check(
+      ...checks: readonly [SchemaAST.Check<T["Type"]>, ...Array<SchemaAST.Check<T["Type"]>>]
+    ): DropConstructorDefault<T>
+    rebuild(ast: T["ast"]): DropConstructorDefault<T>
+  }
+
+// `replaceContext` is `@internal` in `effect/SchemaAST` (stripped from its public types, though the
+// export itself still ships in the compiled JS). Effect's own `withConstructorDefault` goes through the
+// same function internally, so this mirrors an existing code path rather than reaching for something
+// novel, but it's still an internal API that could move or disappear without a signal.
+const SchemaASTInternal = SchemaAST as unknown as {
+  readonly replaceContext: <A extends SchemaAST.AST>(ast: A, context: SchemaAST.Context | undefined) => A
+}
+
+export interface DropConstructorDefaultLambda extends Struct.Lambda {
+  <T extends S.Top>(self: T): DropConstructorDefault<T>
+  readonly "~lambda.out": DropConstructorDefault<this["~lambda.in"] & S.Top>
+}
+
+/**
+ * A `Struct.Lambda` that removes a field's `withConstructorDefault`, if any.
+ * Compose with `Struct.pick`/`Struct.omit` via `Struct.map` to derive a
+ * partial-update schema from a "create" schema without inheriting defaults
+ * that would resurrect omitted fields in `.make(...)` output:
+ *
+ * ```ts
+ * import { flow } from "effect/Function"
+ * import * as Struct from "effect/Struct"
+ * import * as S from "effect-app/Schema"
+ *
+ * const Person = S.Struct({
+ *   id: S.String,
+ *   name: S.String.pipe(S.optionalKey, S.withConstructorDefault(() => ""))
+ * })
+ *
+ * const UpdatePerson = Person.mapFields(
+ *   flow(Struct.omit(["id"]), Struct.map(S.dropConstructorDefault))
+ * )
+ * ```
+ */
+export const dropConstructorDefault: DropConstructorDefaultLambda = Struct.lambda<DropConstructorDefaultLambda>(
+  (schema) => {
+    const context = schema.ast.context
+    if (!context?.constructorDefault) return schema
+    return schema.rebuild(
+      SchemaASTInternal.replaceContext(
+        schema.ast,
+        new SchemaAST.Context(context.isOptional, context.isMutable, undefined, context.annotations)
+      )
+    )
+  }
+)
+
 export function makeExactOptional<NER extends S.Struct.Fields>(
   t: NER
 ): {
-  [K in keyof NER]: NER[K] extends S.Top ? ReturnType<typeof S.optionalKey<NER[K] & S.Top>> : any
+  [K in keyof NER]: NER[K] extends S.Top ? DropConstructorDefault<ReturnType<typeof S.optionalKey<NER[K] & S.Top>>>
+    : any
 } {
   return typedKeysOf(t).reduce((prev, cur) => {
-    prev[cur] = S.optionalKey(t[cur] as any)
+    prev[cur] = dropConstructorDefault(S.optionalKey(t[cur] as any))
     return prev
   }, {} as any)
 }
@@ -209,20 +611,20 @@ export const transformTo = <To extends S.Top, From extends S.Top>(
   from.pipe(
     S.decodeTo(
       to,
-      SchemaTransformation.transformOrFail({
+      SchemaTransformation.transformEffect({
         decode: (input: any, options: any) => Effect.sync(() => decode(input, options)),
         encode: (i: any) =>
           Effect.fail(
             new SchemaIssue.Forbidden(
-              Option.some(i),
-              { message: "One way schema transformation, encoding is not allowed" }
+              { message: "One way schema transformation, encoding is not allowed" },
+              i
             )
           )
-      }) as any
+      })
     )
   )
 
-/** A version of transformOrFail which is only a one way mapping of From->To */
+/** A version of transformEffect which is only a one way mapping of From->To */
 export const transformToOrFail = <To extends S.Top, From extends S.Top, RD>(
   from: From,
   to: To,
@@ -234,43 +636,45 @@ export const transformToOrFail = <To extends S.Top, From extends S.Top, RD>(
   from.pipe(
     S.decodeTo(
       to,
-      SchemaTransformation.transformOrFail({
-        decode: decode as any,
+      SchemaTransformation.transformEffect({
+        decode,
         encode: (i: any) =>
           Effect.fail(
             new SchemaIssue.Forbidden(
-              Option.some(i),
-              { message: "One way schema transformation, encoding is not allowed" }
+              { message: "One way schema transformation, encoding is not allowed" },
+              i
             )
           )
-      }) as any
+      })
     )
   )
 
-export const provide = <Self extends S.Top, R>(
-  self: Self,
-  context: ServiceMap.ServiceMap<R>
-): ProvidedCodec<Self, R> => {
+export const provide: {
+  <R>(context: Context.Context<R>): <Self extends S.Top>(self: Self) => ProvidedCodec<Self, R>
+  <Self extends S.Top, R>(self: Self, context: Context.Context<R>): ProvidedCodec<Self, R>
+} = Function.dual(2, <Self extends S.Top, R>(self: Self, context: Context.Context<R>): ProvidedCodec<Self, R> => {
   const prov = Effect.provide(context)
   return self.pipe(
     S.middlewareDecoding((effect) => prov(effect)),
     S.middlewareEncoding((effect) => prov(effect))
-  ) as ProvidedCodec<Self, R>
-}
-export const contextFromServices = <
+  )
+})
+export const contextFromServices = Effect.fnUntraced(function*<
   Self extends S.Top,
-  Tags extends ReadonlyArray<ServiceMap.Key<any, any>>
+  Tags extends ReadonlyArray<Context.Key<any, any>>
+>(self: Self, ...services: Tags) {
+  const context: Context.Context<Context.Service.Identifier<Tags[number]>> = Context.pick(...services)(
+    yield* Effect.context<Context.Service.Identifier<Tags[number]>>()
+  )
+  return provide(self, context)
+}) as <
+  Self extends S.Top,
+  Tags extends ReadonlyArray<Context.Key<any, any>>
 >(
   self: Self,
   ...services: Tags
-): Effect.Effect<
-  ProvidedCodec<Self, ServiceMap.Service.Identifier<Tags[number]>>,
+) => Effect.Effect<
+  ProvidedCodec<Self, Context.Service.Identifier<Tags[number]>>,
   never,
-  ServiceMap.Service.Identifier<Tags[number]>
-> =>
-  Effect.gen(function*() {
-    const context: ServiceMap.ServiceMap<ServiceMap.Service.Identifier<Tags[number]>> = ServiceMap.pick(...services)(
-      yield* Effect.services<ServiceMap.Service.Identifier<Tags[number]>>()
-    )
-    return provide(self, context)
-  })
+  Context.Service.Identifier<Tags[number]>
+>