effect-app 4.0.0-beta.210 → 4.0.0-beta.212

package/src/Schema.ts

@@ -10,6 +10,102 @@ import { PhoneNumber as PhoneNumberT, type PhoneNumber as PhoneNumberType } from
 import { type AST } from "./Schema/schema.js"
 import { copy, extendM, type StructuralCopyOrigin } from "./utils.js"
 
+// ---------------------------------------------------------------------------
+// Default helpers — re-exported from effect/Schema
+//
+// The five helpers below are surfaced explicitly so the (important) policy
+// around them lives next to the export. See also the file-level note in
+// `./Schema/ext.ts` and the documented wrappers in
+// `./Schema/ext.ts`, `./Schema/numbers.ts`, `./Schema/moreStrings.ts`,
+// and `./ids.ts`.
+//
+// **Construction-only**: `withConstructorDefault` fills the field when it
+// is omitted from `.make(...)` input. It is NOT applied during decode, so
+// it CANNOT be used to just-in-time migrate database fields. A stored
+// record missing the field will still fail to decode.
+//
+// **`withDecodingDefault*` is discouraged**: a missing field in persisted
+// data 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 over shoving missing fields under the rug.
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a default value used **only** when constructing a value (e.g. via
+ * `.make(...)` or struct constructors) and the field is omitted from input.
+ *
+ * **Not applied during decode.** Decoding a payload that is missing the
+ * field will still raise a parse error. Do **not** rely on this to migrate
+ * database fields just-in-time — see the section header above.
+ *
+ * @see {@link withDecodingDefault} / {@link withDecodingDefaultType} —
+ *   decode-time variants (discouraged for persisted data; use explicit,
+ *   versioned migrations instead).
+ */
+export { withConstructorDefault } from "effect/Schema"
+
+/**
+ * Attach a default value used during decode when the field's `Encoded` value
+ * is missing **or** `undefined`. The default is specified as an `Encoded`
+ * value and threaded through the schema's decode step.
+ *
+ * **Discouraged for 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. Prefer an explicit,
+ * preferably versioned migration of database data — see the section header
+ * above.
+ *
+ * @see {@link withDecodingDefaultKey} — key-absent-only variant
+ * @see {@link withDecodingDefaultType} — `Type`-side variant
+ * @see {@link withConstructorDefault} — for `.make(...)`-time defaults
+ */
+export { withDecodingDefault } from "effect/Schema"
+
+/**
+ * Attach a default value used during decode when the field **key is absent**
+ * (note: not when present and `undefined`). The default is an `Encoded`
+ * value.
+ *
+ * **Discouraged for persisted data** — same reasoning as
+ * {@link withDecodingDefault}. Use explicit, preferably versioned migrations
+ * over decode-time fallbacks.
+ *
+ * @see {@link withDecodingDefault} — value-absent-or-undefined variant
+ * @see {@link withDecodingDefaultTypeKey} — `Type`-side variant
+ * @see {@link withConstructorDefault} — for `.make(...)`-time defaults
+ */
+export { withDecodingDefaultKey } from "effect/Schema"
+
+/**
+ * Attach a default value used during decode when the field is missing **or**
+ * `undefined`. The default is specified as a `Type` value (i.e. on the
+ * decoded side).
+ *
+ * **Discouraged for persisted data** — same reasoning as
+ * {@link withDecodingDefault}. Use explicit, preferably versioned migrations
+ * over decode-time fallbacks.
+ *
+ * @see {@link withDecodingDefault} — `Encoded`-side variant
+ * @see {@link withDecodingDefaultTypeKey} — key-absent-only variant
+ * @see {@link withConstructorDefault} — for `.make(...)`-time defaults
+ */
+export { withDecodingDefaultType } from "effect/Schema"
+
+/**
+ * Attach a default value used during decode when the field **key is absent**
+ * (note: not when present and `undefined`). The default is a `Type` value.
+ *
+ * **Discouraged for persisted data** — same reasoning as
+ * {@link withDecodingDefault}. Use explicit, preferably versioned migrations
+ * over decode-time fallbacks.
+ *
+ * @see {@link withDecodingDefaultKey} — `Encoded`-side variant
+ * @see {@link withDecodingDefaultType} — value-absent-or-undefined variant
+ * @see {@link withConstructorDefault} — for `.make(...)`-time defaults
+ */
+export { withDecodingDefaultTypeKey } from "effect/Schema"
+
 export * from "effect/Schema"
 
 export * from "./Schema/Class.js"

package/src/ids.ts

@@ -10,7 +10,16 @@ export interface RequestIdBrand extends StringIdBrand {
 }
 
 export type RequestId = NonEmptyString255
-// a request id may be made from a span id, which does not comply with StringId schema.
+/**
+ * Schema for a request id.
+ *
+ * A request id may be made from a span id, which does not comply with the
+ * `StringId` schema (hence the looser `NonEmptyString255` base).
+ *
+ * `.withConstructorDefault` => fresh `StringId` (construction-only; not
+ * applied during decode — cannot be used to JIT-migrate database fields).
+ * See `./Schema/ext.ts` for the full policy note.
+ */
 export const RequestId = extendM(
   Object
     .assign(Object.create(NonEmptyString255) as {}, NonEmptyString255 as unknown as Codec<NonEmptyString255, string>),
@@ -18,7 +27,13 @@ export const RequestId = extendM(
     const make = StringId.make as () => NonEmptyString255
     return ({
       make,
-      withDefault: S.withConstructorDefault(Effect.sync(make))(s as typeof s & S.WithoutConstructorDefault)
+      /**
+       * Construction-only default: fresh `StringId`. Applied only when the
+       * field is omitted from `.make(...)` input. NOT applied during decode —
+       * cannot be used to JIT-migrate database fields. See `./Schema/ext.ts`
+       * file-level note.
+       */
+      withConstructorDefault: S.withConstructorDefault(Effect.sync(make))(s as typeof s & S.WithoutConstructorDefault)
     })
   }
 )
@@ -26,4 +41,10 @@ export const RequestId = extendM(
 
 export interface UserProfileIdBrand extends Simplify<B.Brand<"UserProfileId"> & StringIdBrand> {}
 export type UserProfileId = string & UserProfileIdBrand
+/**
+ * Branded `StringId` for user profiles.
+ *
+ * Exposes `.withConstructorDefault` (fresh id) — construction-only; not
+ * applied during decode. See `./Schema/ext.ts` for the full policy note.
+ */
 export const UserProfileId = brandedStringId<UserProfileId>()

package/test/schema.test.ts

@@ -18,11 +18,11 @@ test("literal default works", () => {
   const l = S.Literals(["a", "b"])
   expect(l.Default).toBe("a")
   expectTypeOf(l.Default).toEqualTypeOf<"a">()
-  const s = S.Struct({ l: l.withDefault })
+  const s = S.Struct({ l: l.withConstructorDefault })
   expect(s.make({}).l).toBe("a")
 
   const l2 = l.changeDefault("b")
-  const s2 = S.Struct({ l: l2.withDefault })
+  const s2 = S.Struct({ l: l2.withConstructorDefault })
   expect(s2.make({}).l).toBe("b")
 })
 
@@ -391,10 +391,10 @@ describe("ReadonlyMapFromArray", () => {
   })
 })
 
-describe("ReadonlySet (with withDefault)", () => {
-  test("make provides withDefault", () => {
+describe("ReadonlySet (with withConstructorDefault)", () => {
+  test("make provides withConstructorDefault", () => {
     const schema = S.ReadonlySet(S.NumberFromString)
-    const struct = S.Struct({ items: schema.withDefault })
+    const struct = S.Struct({ items: schema.withConstructorDefault })
     const made = struct.make({})
     expect(made.items).toEqual(new Set())
   })
@@ -406,10 +406,10 @@ describe("ReadonlySet (with withDefault)", () => {
   })
 })
 
-describe("ReadonlyMap (with withDefault)", () => {
-  test("make provides withDefault", () => {
+describe("ReadonlyMap (with withConstructorDefault)", () => {
+  test("make provides withConstructorDefault", () => {
     const schema = S.ReadonlyMap({ key: S.NumberFromString, value: S.String })
-    const struct = S.Struct({ items: schema.withDefault })
+    const struct = S.Struct({ items: schema.withConstructorDefault })
     const made = struct.make({})
     expect(made.items).toEqual(new Map())
   })