effect-app 4.0.0-beta.23 → 4.0.0-beta.230

package/src/Schema/moreStrings.ts

@@ -1,12 +1,23 @@
-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 * 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 { withDefaultMake, type WithDefaults } from "./ext.js"
 import { type B } from "./schema.js"
 import type { NonEmptyString255Brand, NonEmptyStringBrand } from "./strings.js"
 
@@ -27,9 +38,8 @@ export type NonEmptyString50 = string & NonEmptyString50Brand
  */
 export const NonEmptyString50 = nonEmptyString.pipe(
   S.check(S.isMaxLength(50)),
-  fromBrand(nominal<NonEmptyString50>(), {
+  fromBrand<NonEmptyString50>(nominal<NonEmptyString50>(), {
     identifier: "NonEmptyString50",
-    title: "NonEmptyString50",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -50,9 +60,8 @@ export type NonEmptyString64 = string & NonEmptyString64Brand
  */
 export const NonEmptyString64 = nonEmptyString.pipe(
   S.check(S.isMaxLength(64)),
-  fromBrand(nominal<NonEmptyString64>(), {
+  fromBrand<NonEmptyString64>(nominal<NonEmptyString64>(), {
     identifier: "NonEmptyString64",
-    title: "NonEmptyString64",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -74,9 +83,8 @@ export type NonEmptyString80 = string & NonEmptyString80Brand
 
 export const NonEmptyString80 = nonEmptyString.pipe(
   S.check(S.isMaxLength(80)),
-  fromBrand(nominal<NonEmptyString80>(), {
+  fromBrand<NonEmptyString80>(nominal<NonEmptyString80>(), {
     identifier: "NonEmptyString80",
-    title: "NonEmptyString80",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -97,9 +105,8 @@ export type NonEmptyString100 = string & NonEmptyString100Brand
  */
 export const NonEmptyString100 = nonEmptyString.pipe(
   S.check(S.isMaxLength(100)),
-  fromBrand(nominal<NonEmptyString100>(), {
+  fromBrand<NonEmptyString100>(nominal<NonEmptyString100>(), {
     identifier: "NonEmptyString100",
-    title: "NonEmptyString100",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -121,7 +128,10 @@ export type Min3String255 = string & Min3String255Brand
 export const Min3String255 = 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
 )
 
@@ -135,7 +145,8 @@ export interface StringIdBrand extends Simplify<B.Brand<"StringId"> & NonEmptySt
  */
 export type StringId = string & StringIdBrand
 
-const makeStringId = (): StringId => nanoid() as unknown as StringId
+const makeStringId = (s?: string): StringId =>
+  s !== undefined ? S.decodeSync(StringId)(s) : nanoid() as unknown as StringId
 const minLength = 6
 const maxLength = 50
 const size = 21
@@ -146,21 +157,29 @@ const StringIdArb = (): S.LazyArbitrary<StringId> => (fc) =>
     .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>(), {
+    fromBrand<StringId>(nominal<StringId>(), {
       identifier: "StringId",
-      title: "StringId",
       toArbitrary: () => (fc) => StringIdArb()(fc),
       jsonSchema: {}
     })
   ),
   (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)
@@ -169,7 +188,15 @@ export const StringId = extendM(
 
 // 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,
@@ -177,27 +204,26 @@ export function prefixedStringId<Brand extends StringId>() {
   ) => {
     type FullPrefix = `${Prefix}${Separator}`
     const pref = `${prefix}${separator ?? "-"}` as FullPrefix
-    const arb = (): S.LazyArbitrary<string & Brand> => (fc) =>
+    const arb = (): S.LazyArbitrary<Type> => (fc) =>
       StringIdArb()(fc).map(
-        (x) => (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 = StringId
       .pipe(
-        S.refine((x: string): x is string & Brand => x.startsWith(pref), {
-          identifier: name,
-          title: name
+        S.refine((x: string): x is Type => x.startsWith(pref), {
+          identifier: name
         }),
         S.annotate({
           toArbitrary: () => (fc) => arb()(fc)
         })
-      ) as S.Codec<string & Brand, string>
+      )
     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.
@@ -208,32 +234,59 @@ 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)
+          )
+        )
       })
     )
   }
 }
 
+/**
+ * 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 = <
-  Brand extends StringIdBrand
+  Id
 >() =>
   withDefaultMake(
-    Object.assign(Object.create(StringId), StringId) as S.Codec<string & Brand, string> & {
-      make: () => string & Brand
-      withDefault: S.withConstructorDefault<S.Codec<string & Brand, string> & S.WithoutConstructorDefault>
-    } & WithDefaults<S.Codec<string & Brand, string>>
+    Object.assign(Object.create(StringId), StringId) as S.Codec<Id, string> & {
+      /**
+       * Construction-only default: fresh `nanoid()`-shaped 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: S.withConstructorDefault<S.Codec<Id, string> & S.WithoutConstructorDefault>
+      make: () => Id
+    } & WithDefaults<S.Codec<Id, string>>
   )
 
 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: S.withConstructorDefault<S.Codec<Brand, string> & S.WithoutConstructorDefault>
+  /**
+   * 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> {}
@@ -247,9 +300,12 @@ const isUrl: Refinement<string, Url> = (s: string): s is Url => {
 export const Url = S
   .String
   .pipe(
+    S.annotate({
+      title: "Url",
+      format: "uri"
+    }),
     S.refine(isUrl, {
       identifier: "Url",
-      title: "Url",
       jsonSchema: { format: "uri" }
     }),
     S.annotate({

package/src/Schema/numbers.ts

@@ -1,74 +1,122 @@
+/**
+ * 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 { withDefaultMake } from "./ext.js"
 import { type B } from "./schema.js"
 
 export interface PositiveIntBrand
   extends Simplify<B.Brand<"PositiveInt"> & NonNegativeIntBrand & PositiveNumberBrand>
 {}
+/** Positive integer. `.withConstructorDefault` => `1` (construction-only). */
 export const PositiveInt = 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> {}
+/** Non-negative integer. `.withConstructorDefault` => `0` (construction-only). */
 export const NonNegativeInt = 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">> {}
+/** Integer. `.withConstructorDefault` => `0` (construction-only). */
 export const Int = extendM(
-  S.Int.pipe(fromBrand(nominal<Int>(), { identifier: "Int", title: "Int", jsonSchema: {} }), withDefaultMake),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => s(0))) })
+  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 type Int = number & IntBrand
 
 export interface PositiveNumberBrand extends Simplify<B.Brand<"PositiveNumber"> & NonNegativeNumberBrand> {}
+/** Positive finite number. `.withConstructorDefault` => `1` (construction-only). */
 export const PositiveNumber = extendM(
-  S.Number.pipe(
+  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">> {}
+/** Non-negative finite number. `.withConstructorDefault` => `0` (construction-only). */
 export const NonNegativeNumber = 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
 

package/src/Schema/phoneNumber.ts

@@ -13,9 +13,13 @@ 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",
       jsonSchema: { format: "phone" }
     }),

package/src/Schema/strings.ts

@@ -9,9 +9,8 @@ export type NonEmptyString = string & NonEmptyStringBrand
 export const NonEmptyString = S
   .NonEmptyString
   .pipe(
-    fromBrand(nominal<NonEmptyString>(), {
+    fromBrand<NonEmptyString>(nominal<NonEmptyString>(), {
       identifier: "NonEmptyString",
-      title: "NonEmptyString",
       jsonSchema: {}
     }),
     withDefaultMake
@@ -23,9 +22,8 @@ export const NonEmptyString64k = S
   .NonEmptyString
   .pipe(
     S.check(S.isMaxLength(64 * 1024)),
-    fromBrand(nominal<NonEmptyString64k>(), {
+    fromBrand<NonEmptyString64k>(nominal<NonEmptyString64k>(), {
       identifier: "NonEmptyString64k",
-      title: "NonEmptyString64k",
       jsonSchema: {}
     }),
     withDefaultMake
@@ -37,9 +35,8 @@ export const NonEmptyString2k = S
   .NonEmptyString
   .pipe(
     S.check(S.isMaxLength(2 * 1024)),
-    fromBrand(nominal<NonEmptyString2k>(), {
+    fromBrand<NonEmptyString2k>(nominal<NonEmptyString2k>(), {
       identifier: "NonEmptyString2k",
-      title: "NonEmptyString2k",
       jsonSchema: {}
     }),
     withDefaultMake
@@ -51,9 +48,8 @@ export const NonEmptyString255 = S
   .NonEmptyString
   .pipe(
     S.check(S.isMaxLength(255)),
-    fromBrand(nominal<NonEmptyString255>(), {
+    fromBrand<NonEmptyString255>(nominal<NonEmptyString255>(), {
       identifier: "NonEmptyString255",
-      title: "NonEmptyString255",
       jsonSchema: {}
     }),
     withDefaultMake