effect-app 4.0.0-beta.3 → 4.0.0-beta.300

package/src/Schema/moreStrings.ts

@@ -1,21 +1,34 @@
-import { pipe } from "effect"
+/**
+ * Branded string ID schemas with `.withConstructorDefault` extensions.
+ *
+ * Each `.withConstructorDefault` here is **only** applied when the field is
+ * omitted during construction (`.make(...)`). It is **not** applied during
+ * decode and therefore cannot be used to JIT-migrate database fields.
+ *
+ * For persisted data, prefer an explicit, preferably versioned migration
+ * over decode-time fallbacks. See `./ext.ts` for the full policy note.
+ */
 import type { Refinement } from "effect-app/Function"
 import { extendM } from "effect-app/utils"
+import type * as B from "effect/Brand"
+import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
 import * as S from "effect/Schema"
 import type { Simplify } from "effect/Types"
 import { customRandom, nanoid, urlAlphabet } from "nanoid"
 import validator from "validator"
-import { fromBrand, nominal } from "./brand.js"
-import { withDefaultConstructor, withDefaultMake, type WithDefaults } from "./ext.js"
-import { type B } from "./schema.js"
-import type { NonEmptyString255Brand, NonEmptyStringBrand } from "./strings.js"
+import type * as SchemaAST from "../SchemaAST.ts"
+import { type BrandedSchema, fromBrand, nominal } from "./brand.ts"
+import { withDefaultMake } from "./ext.ts"
+import { type B as SchemaB } from "./schema.ts"
+import type { NonEmptyString255Brand, NonEmptyStringBrand } from "./strings.ts"
 
 const nonEmptyString = S.NonEmptyString
 
 /**
  * A string that is at least 1 character long and a maximum of 50.
  */
-export interface NonEmptyString50Brand extends Simplify<B.Brand<"NonEmptyString50"> & NonEmptyString64Brand> {}
+export interface NonEmptyString50Brand extends Simplify<SchemaB.Brand<"NonEmptyString50"> & NonEmptyString64Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 50.
@@ -25,11 +38,13 @@ export type NonEmptyString50 = string & NonEmptyString50Brand
 /**
  * A string that is at least 1 character long and a maximum of 50.
  */
-export const NonEmptyString50 = nonEmptyString.pipe(
+export interface NonEmptyString50Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString50> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString50
+}
+export const NonEmptyString50: NonEmptyString50Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(50)),
-  fromBrand(nominal<NonEmptyString50>(), {
+  fromBrand<NonEmptyString50>(nominal<NonEmptyString50>(), {
     identifier: "NonEmptyString50",
-    title: "NonEmptyString50",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -38,7 +53,7 @@ export const NonEmptyString50 = nonEmptyString.pipe(
 /**
  * A string that is at least 1 character long and a maximum of 64.
  */
-export interface NonEmptyString64Brand extends Simplify<B.Brand<"NonEmptyString64"> & NonEmptyString80Brand> {}
+export interface NonEmptyString64Brand extends Simplify<SchemaB.Brand<"NonEmptyString64"> & NonEmptyString80Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 64.
@@ -48,11 +63,13 @@ export type NonEmptyString64 = string & NonEmptyString64Brand
 /**
  * A string that is at least 1 character long and a maximum of 64.
  */
-export const NonEmptyString64 = nonEmptyString.pipe(
+export interface NonEmptyString64Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString64> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString64
+}
+export const NonEmptyString64: NonEmptyString64Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(64)),
-  fromBrand(nominal<NonEmptyString64>(), {
+  fromBrand<NonEmptyString64>(nominal<NonEmptyString64>(), {
     identifier: "NonEmptyString64",
-    title: "NonEmptyString64",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -61,7 +78,7 @@ export const NonEmptyString64 = nonEmptyString.pipe(
 /**
  * A string that is at least 1 character long and a maximum of 80.
  */
-export interface NonEmptyString80Brand extends Simplify<B.Brand<"NonEmptyString80"> & NonEmptyString100Brand> {}
+export interface NonEmptyString80Brand extends Simplify<SchemaB.Brand<"NonEmptyString80"> & NonEmptyString100Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 80.
@@ -72,11 +89,13 @@ export type NonEmptyString80 = string & NonEmptyString80Brand
  * A string that is at least 1 character long and a maximum of 80.
  */
 
-export const NonEmptyString80 = nonEmptyString.pipe(
+export interface NonEmptyString80Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString80> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString80
+}
+export const NonEmptyString80: NonEmptyString80Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(80)),
-  fromBrand(nominal<NonEmptyString80>(), {
+  fromBrand<NonEmptyString80>(nominal<NonEmptyString80>(), {
     identifier: "NonEmptyString80",
-    title: "NonEmptyString80",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -85,7 +104,7 @@ export const NonEmptyString80 = nonEmptyString.pipe(
 /**
  * A string that is at least 1 character long and a maximum of 100.
  */
-export interface NonEmptyString100Brand extends Simplify<B.Brand<"NonEmptyString100"> & NonEmptyString255Brand> {}
+export interface NonEmptyString100Brand extends Simplify<SchemaB.Brand<"NonEmptyString100"> & NonEmptyString255Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 100.
@@ -95,11 +114,13 @@ export type NonEmptyString100 = string & NonEmptyString100Brand
 /**
  * A string that is at least 1 character long and a maximum of 100.
  */
-export const NonEmptyString100 = nonEmptyString.pipe(
+export interface NonEmptyString100Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString100> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString100
+}
+export const NonEmptyString100: NonEmptyString100Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(100)),
-  fromBrand(nominal<NonEmptyString100>(), {
+  fromBrand<NonEmptyString100>(nominal<NonEmptyString100>(), {
     identifier: "NonEmptyString100",
-    title: "NonEmptyString100",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -108,7 +129,7 @@ export const NonEmptyString100 = nonEmptyString.pipe(
 /**
  * A string that is at least 3 character long and a maximum of 255.
  */
-export interface Min3String255Brand extends Simplify<B.Brand<"Min3String255"> & NonEmptyString255Brand> {}
+export interface Min3String255Brand extends Simplify<SchemaB.Brand<"Min3String255"> & NonEmptyString255Brand> {}
 
 /**
  * A string that is at least 3 character long and a maximum of 255.
@@ -118,59 +139,86 @@ export type Min3String255 = string & Min3String255Brand
 /**
  * A string that is at least 3 character long and a maximum of 255.
  */
-export const Min3String255 = pipe(
+export interface Min3String255Schema extends BrandedSchema<S.String, Min3String255> {
+  (i: string, options?: SchemaAST.ParseOptions): Min3String255
+}
+export const Min3String255: Min3String255Schema = pipe(
   S.String,
   S.check(S.isMinLength(3), S.isMaxLength(255)),
-  fromBrand(nominal<Min3String255>(), { identifier: "Min3String255", title: "Min3String255", jsonSchema: {} }),
+  fromBrand<Min3String255>(nominal<Min3String255>(), {
+    identifier: "Min3String255",
+    jsonSchema: {}
+  }),
   withDefaultMake
 )
 
 /**
  * A string that is at least 6 characters long and a maximum of 50.
  */
-export interface StringIdBrand extends Simplify<B.Brand<"StringId"> & NonEmptyString50Brand> {}
+export interface StringIdBrand extends Simplify<SchemaB.Brand<"StringId"> & NonEmptyString50Brand> {}
 
 /**
  * A string that is at least 6 characters long and a maximum of 50.
  */
 export type StringId = string & StringIdBrand
 
-const makeStringId = (): StringId => nanoid() as unknown as StringId
 const minLength = 6
 const maxLength = 50
 const size = 21
 const length = 10 * size
-const StringIdArb = (): any => (fc: any) =>
+const StringIdSchemaBase = pipe(
+  S.String,
+  S.check(S.isMinLength(minLength), S.isMaxLength(maxLength)),
+  fromBrand<StringId>(nominal<StringId>(), {
+    identifier: "StringId",
+    toArbitrary: () => (fc) => StringIdArb()(fc),
+    jsonSchema: {}
+  })
+)
+const makeStringId = (s?: string): StringId =>
+  s !== undefined ? S.decodeSync(StringIdSchemaBase)(s) : nanoid() as unknown as StringId
+const StringIdArb = (): S.LazyArbitrary<StringId> => (fc) =>
   fc
     .uint8Array({ minLength: length, maxLength: length })
-    .map((_: any) => customRandom(urlAlphabet, size, (size: number) => _.subarray(0, size))())
-
+    .map((_) => customRandom(urlAlphabet, size, (size) => _.subarray(0, size))() as StringId)
 /**
  * A string that is at least 6 characters long and a maximum of 50.
+ *
+ * `.withConstructorDefault` => fresh `nanoid()` (construction-only; not
+ * applied during decode — see file-level note).
  */
-export const StringId = extendM(
-  pipe(
-    S.String,
-    S.check(S.isMinLength(minLength), S.isMaxLength(maxLength)),
-    fromBrand(nominal<StringId>(), {
-      identifier: "StringId",
-      title: "StringId",
-      arbitrary: StringIdArb,
-      jsonSchema: {}
-    })
-  ),
+export interface StringIdSchema extends BrandedSchema<S.String, StringId> {
+  (i: string, options?: SchemaAST.ParseOptions): StringId
+  /** Generate fresh `nanoid()`-shaped `StringId`. */
+  make(): StringId
+  /** Construct a `StringId` from a known string (validated via decodeSync). */
+  make(input: string, options?: S.MakeOptions): StringId
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.String, StringId>>
+}
+export const StringId: StringIdSchema = extendM(
+  StringIdSchemaBase,
   (s) => ({
     make: makeStringId,
-    withDefault: s.pipe(withDefaultConstructor(makeStringId))
+    /**
+     * Construction-only default: fresh `nanoid()`-shaped `StringId`. 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(makeStringId)))
   })
 )
   .pipe(withDefaultMake)
 
-// const prefixedStringIdUnsafe = (prefix: string) => StringId(prefix + StringId.make())
-
-// const prefixedStringIdUnsafeThunk = (prefix: string) => () => prefixedStringIdUnsafe(prefix)
-
-export function prefixedStringId<Brand extends StringId>() {
+/**
+ * Build a `StringId` schema whose values are required to start with a fixed
+ * `prefix` (joined with `separator`, default `-`).
+ *
+ * The returned schema exposes `.withConstructorDefault` that mints a fresh
+ * prefixed id. Construction-only — not applied during decode; see file-level
+ * note.
+ */
+export function prefixedStringId<Type extends StringId>() {
   return <Prefix extends string, Separator extends string = "-">(
     prefix: Prefix,
     name: string,
@@ -178,25 +226,26 @@ export function prefixedStringId<Brand extends StringId>() {
   ) => {
     type FullPrefix = `${Prefix}${Separator}`
     const pref = `${prefix}${separator ?? "-"}` as FullPrefix
-    const arb = (): any => (fc: any) =>
+    const arb = (): S.LazyArbitrary<Type> => (fc) =>
       StringIdArb()(fc).map(
-        (x: any) => (pref + x.substring(0, 50 - pref.length)) as Brand
+        (x) => (pref + x.substring(0, 50 - pref.length)) as Type
       )
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    const s: S.Codec<string & Brand, string> = StringId
+    const s = StringIdSchemaBase
       .pipe(
-        S.refine((x: string): x is string & Brand => x.startsWith(pref), {
-          arbitrary: arb,
-          identifier: name,
-          title: name
+        S.refine((x: string): x is Type => x.startsWith(pref), {
+          identifier: name
+        }),
+        S.annotate({
+          toArbitrary: () => (fc) => arb()(fc)
         })
-      ) as any
+      )
     const schema = s.pipe(withDefaultMake)
-    const make = () => (pref + StringId.make().substring(0, 50 - pref.length)) as Brand
+    const make = () => (pref + StringId.make().substring(0, 50 - pref.length)) as Type
 
     return extendM(
       schema,
-      (ex): PrefixedStringUtils<Brand, Prefix, Separator> => ({
+      (ex): PrefixedStringUtils<Type, Prefix, Separator> => ({
         make,
         /**
          * Automatically adds the prefix.
@@ -207,35 +256,60 @@ export function prefixedStringId<Brand extends StringId>() {
          */
         prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => ex(str),
         prefix,
-        withDefault: schema.pipe(withDefaultConstructor(make))
+        /**
+         * Construction-only default: fresh prefixed id. 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: schema.pipe(
+          S.withConstructorDefault<S.Codec<Type, string> & S.WithoutConstructorDefault>(
+            Effect.sync(make)
+          )
+        )
       })
     )
   }
 }
 
-export const brandedStringId = <
-  Brand extends StringIdBrand
->() =>
+/**
+ * Build a branded `StringId` schema for the given branded `Id` type.
+ *
+ * Exposes `.withConstructorDefault` that mints a fresh `nanoid()`-shaped id.
+ * Construction-only — not applied during decode; see file-level note.
+ */
+export const brandedStringId = <Id extends string & B.Brand<any>>(): BrandedStringIdSchema<Id> =>
   withDefaultMake(
-    Object.assign(Object.create(StringId), StringId) as S.Codec<string & Brand> & {
-      make: () => string & Brand
-      withDefault: any
-    } & WithDefaults<S.Codec<string & Brand>>
+    Object.assign(Object.create(StringId), StringId) as BrandedStringIdSchema<Id>
   )
 
 export interface PrefixedStringUtils<
-  Brand extends StringId,
+  Type extends StringId,
   Prefix extends string,
   Separator extends string
 > {
-  readonly make: () => Brand
-  readonly unsafeFrom: (str: string) => Brand
-  prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => Brand
+  readonly make: () => Type
+  readonly unsafeFrom: (str: string) => Type
+  prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => Type
   readonly prefix: Prefix
-  readonly withDefault: any
+  /**
+   * Construction-only default: fresh prefixed id. 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.
+   */
+  readonly withConstructorDefault: S.withConstructorDefault<S.Codec<Type, string> & S.WithoutConstructorDefault>
 }
 
-export interface UrlBrand extends Simplify<B.Brand<"Url"> & NonEmptyStringBrand> {}
+export interface BrandedStringIdSchema<Id extends string & B.Brand<any>> extends BrandedSchema<S.String, Id> {
+  (i: string, options?: SchemaAST.ParseOptions): Id
+  /** Generate fresh `nanoid()`-shaped id (inherited from `StringId`). */
+  make(): Id
+  /** Construct an `Id` from a known string (validated via decodeSync). */
+  make(input: string, options?: S.MakeOptions): Id
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.String, Id>>
+}
+
+export interface UrlBrand extends Simplify<SchemaB.Brand<"Url"> & NonEmptyStringBrand> {}
 
 export type Url = string & UrlBrand
 
@@ -243,14 +317,22 @@ const isUrl: Refinement<string, Url> = (s: string): s is Url => {
   return validator.default.isURL(s, { require_tld: false })
 }
 
-export const Url = S
+export interface UrlSchema extends S.refine<Url, S.String> {
+  (i: string, options?: SchemaAST.ParseOptions): Url
+}
+export const Url: UrlSchema = S
   .String
   .pipe(
+    S.annotate({
+      title: "Url",
+      format: "uri"
+    }),
     S.refine(isUrl, {
-      arbitrary: (): any => (fc: any) => fc.webUrl().map((_: any) => _ as Url),
       identifier: "Url",
-      title: "Url",
       jsonSchema: { format: "uri" }
     }),
+    S.annotate({
+      toArbitrary: () => (fc) => fc.webUrl().map((_) => _ as Url)
+    }),
     withDefaultMake
   )

package/src/Schema/numbers.ts

@@ -1,76 +1,145 @@
+/**
+ * Numeric brand schemas with `.withConstructorDefault` extensions.
+ *
+ * Each `.withConstructorDefault` here is **only** applied when the field is
+ * omitted during construction (`.make(...)`). It is **not** applied during
+ * decode and therefore cannot be used to JIT-migrate database fields.
+ *
+ * For persisted data, prefer an explicit, preferably versioned migration
+ * over decode-time fallbacks. See `./ext.ts` for the full policy note.
+ */
 import { extendM } from "effect-app/utils"
+import * as Effect from "effect/Effect"
 import * as S from "effect/Schema"
 import type { Simplify } from "effect/Types"
-import { fromBrand, nominal } from "./brand.js"
-import { withDefaultConstructor, withDefaultMake } from "./ext.js"
-import { type B } from "./schema.js"
+import type * as SchemaAST from "../SchemaAST.ts"
+import { type BrandedSchema, fromBrand, nominal } from "./brand.ts"
+import { withDefaultMake } from "./ext.ts"
+import { type B } from "./schema.ts"
 
 export interface PositiveIntBrand
   extends Simplify<B.Brand<"PositiveInt"> & NonNegativeIntBrand & PositiveNumberBrand>
 {}
-export const PositiveInt = extendM(
+export type PositiveInt = number & PositiveIntBrand
+/** Positive integer. `.withConstructorDefault` => `1` (construction-only). */
+export interface PositiveIntSchema extends BrandedSchema<S.Int, PositiveInt> {
+  (i: number, options?: SchemaAST.ParseOptions): PositiveInt
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Int, PositiveInt>>
+}
+export const PositiveInt: PositiveIntSchema = extendM(
   S.Int.pipe(
     S.check(S.isGreaterThan(0)),
-    fromBrand(nominal<PositiveInt>(), { identifier: "PositiveInt", title: "PositiveInt", jsonSchema: {} }),
+    fromBrand<PositiveInt>(nominal<PositiveInt>(), { identifier: "PositiveInt", jsonSchema: {} }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => s(1))) })
+  (s) => ({
+    /**
+     * Construction-only default `1`. 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(() => s(1))))
+  })
 )
-export type PositiveInt = number & PositiveIntBrand
 
 export interface NonNegativeIntBrand extends Simplify<B.Brand<"NonNegativeInt"> & IntBrand & NonNegativeNumberBrand> {}
-export const NonNegativeInt = extendM(
+export type NonNegativeInt = number & NonNegativeIntBrand
+/** Non-negative integer. `.withConstructorDefault` => `0` (construction-only). */
+export interface NonNegativeIntSchema extends BrandedSchema<S.Int, NonNegativeInt> {
+  (i: number, options?: SchemaAST.ParseOptions): NonNegativeInt
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Int, NonNegativeInt>>
+}
+export const NonNegativeInt: NonNegativeIntSchema = extendM(
   S.Int.pipe(
     S.check(S.isGreaterThanOrEqualTo(0)),
-    fromBrand(nominal<NonNegativeInt>(), {
+    fromBrand<NonNegativeInt>(nominal<NonNegativeInt>(), {
       identifier: "NonNegativeInt",
-      title: "NonNegativeInt",
       jsonSchema: {}
     }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => s(0))) })
+  (s) => ({
+    /**
+     * 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.pipe(S.withConstructorDefault(Effect.sync(() => s(0))))
+  })
 )
-export type NonNegativeInt = number & NonNegativeIntBrand
 
 export interface IntBrand extends Simplify<B.Brand<"Int">> {}
-export const Int = extendM(
-  S.Int.pipe(fromBrand(nominal<Int>(), { identifier: "Int", title: "Int", jsonSchema: {} }), withDefaultMake),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => s(0))) })
-)
 export type Int = number & IntBrand
+/** Integer. `.withConstructorDefault` => `0` (construction-only). */
+export interface IntSchema extends BrandedSchema<S.Int, Int> {
+  (i: number, options?: SchemaAST.ParseOptions): Int
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Int, Int>>
+}
+export const Int: IntSchema = extendM(
+  S.Int.pipe(fromBrand<Int>(nominal<Int>(), { identifier: "Int", jsonSchema: {} }), withDefaultMake),
+  (s) => ({
+    /**
+     * 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.pipe(S.withConstructorDefault(Effect.sync(() => s(0))))
+  })
+)
 
 export interface PositiveNumberBrand extends Simplify<B.Brand<"PositiveNumber"> & NonNegativeNumberBrand> {}
-export const PositiveNumber = extendM(
-  S.Number.pipe(
+export type PositiveNumber = number & PositiveNumberBrand
+/** Positive finite number. `.withConstructorDefault` => `1` (construction-only). */
+export interface PositiveNumberSchema extends BrandedSchema<S.Finite, PositiveNumber> {
+  (i: number, options?: SchemaAST.ParseOptions): PositiveNumber
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Finite, PositiveNumber>>
+}
+export const PositiveNumber: PositiveNumberSchema = extendM(
+  S.Finite.pipe(
     S.check(S.isGreaterThan(0)),
-    fromBrand(nominal<PositiveNumber>(), {
+    fromBrand<PositiveNumber>(nominal<PositiveNumber>(), {
       identifier: "PositiveNumber",
-      title: "PositiveNumber",
       jsonSchema: {}
     }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => s(1))) })
+  (s) => ({
+    /**
+     * Construction-only default `1`. 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(() => s(1))))
+  })
 )
-export type PositiveNumber = number & PositiveNumberBrand
 
 export interface NonNegativeNumberBrand extends Simplify<B.Brand<"NonNegativeNumber">> {}
-export const NonNegativeNumber = extendM(
+export type NonNegativeNumber = number & NonNegativeNumberBrand
+/** Non-negative finite number. `.withConstructorDefault` => `0` (construction-only). */
+export interface NonNegativeNumberSchema extends BrandedSchema<S.Finite, NonNegativeNumber> {
+  (i: number, options?: SchemaAST.ParseOptions): NonNegativeNumber
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Finite, NonNegativeNumber>>
+}
+export const NonNegativeNumber: NonNegativeNumberSchema = extendM(
   S
-    .Number
+    .Finite
     .pipe(
       S.check(S.isGreaterThanOrEqualTo(0)),
-      fromBrand(nominal<NonNegativeNumber>(), {
+      fromBrand<NonNegativeNumber>(nominal<NonNegativeNumber>(), {
         identifier: "NonNegativeNumber",
-        title: "NonNegativeNumber",
         jsonSchema: {}
       }),
       withDefaultMake
     ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => s(0))) })
+  (s) => ({
+    /**
+     * 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.pipe(S.withConstructorDefault(Effect.sync(() => s(0))))
+  })
 )
-export type NonNegativeNumber = number & NonNegativeNumberBrand
 
 /** @deprecated Not an actual decimal */
 export const NonNegativeDecimal = NonNegativeNumber

package/src/Schema/phoneNumber.ts

@@ -2,10 +2,10 @@ import type { Refinement } from "effect-app/Function"
 import { isValidPhone } from "effect-app/validation"
 import * as S from "effect/Schema"
 import type { Simplify } from "effect/Types"
-import { withDefaultMake } from "./ext.js"
-import { Numbers } from "./FastCheck.js"
-import type { B } from "./schema.js"
-import type { NonEmptyStringBrand } from "./strings.js"
+import { withDefaultMake } from "./ext.ts"
+import { Numbers } from "./FastCheck.ts"
+import type { B } from "./schema.ts"
+import type { NonEmptyStringBrand } from "./strings.ts"
 
 export interface PhoneNumberBrand extends Simplify<B.Brand<"PhoneNumber"> & NonEmptyStringBrand> {}
 export type PhoneNumber = string & PhoneNumberBrand
@@ -13,12 +13,18 @@ export type PhoneNumber = string & PhoneNumberBrand
 export const PhoneNumber = S
   .String
   .pipe(
+    S.annotate({
+      title: "PhoneNumber",
+      description: "a phone number with at least 7 digits",
+      format: "phone"
+    }),
     S.refine(isValidPhone as Refinement<string, PhoneNumber>, {
       identifier: "PhoneNumber",
-      title: "PhoneNumber",
       description: "a phone number with at least 7 digits",
-      arbitrary: () => (fc: any) => Numbers(7, 10)(fc).map((_: any) => _ as PhoneNumber),
       jsonSchema: { format: "phone" }
     }),
+    S.annotate({
+      toArbitrary: () => (fc) => Numbers(7, 10)(fc).map((_) => _ as PhoneNumber)
+    }),
     withDefaultMake
   )

package/src/Schema/schema.ts

@@ -1,5 +1,5 @@
 import * as B from "effect/Brand"
-import * as AST from "effect/SchemaAST"
 import * as P from "effect/SchemaParser"
+import * as AST from "../SchemaAST.ts"
 
 export { AST, B, P }