effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/schema/Model.ts

@@ -1,4 +1,22 @@
 /**
+ * Utilities for defining schema-backed domain models that need different shapes
+ * for database access and JSON APIs.
+ *
+ * A model defined with this module keeps one field declaration as the source of
+ * truth and derives the `select`, `insert`, `update`, `json`, `jsonCreate`, and
+ * `jsonUpdate` variants from it. This is useful for persistence models whose
+ * database representation differs from the public API, for example generated
+ * columns, application-generated identifiers, sensitive fields that must not be
+ * serialized to JSON, nullable database columns exposed as `Option`, SQLite
+ * booleans, JSON stored as text, date-time audit columns, and generated UUIDs.
+ *
+ * Each variant is a schema in its own right, so choose the variant that matches
+ * the boundary you are validating or encoding. Plain schemas are included in all
+ * variants, while `Field` helpers opt a property into only the variants they
+ * declare. Overrideable defaults such as timestamp helpers can still be provided
+ * explicitly with `Override`, and JSON variants may differ from database variants
+ * in both optionality and encoded representation.
+ *
  * @since 4.0.0
  */
 import * as Uuid from "uuid"
@@ -27,8 +45,11 @@ const {
 })
 
 /**
- * @since 4.0.0
+ * Base shape of a variant model schema, including its fields and the generated
+ * database and JSON variant schemas.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Any = Schema.Top & {
   readonly fields: Schema.Struct.Fields
@@ -40,14 +61,18 @@ export type Any = Schema.Top & {
 }
 
 /**
- * @since 4.0.0
+ * Database-facing variant names generated for model schemas.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type VariantsDatabase = "select" | "insert" | "update"
 
 /**
- * @since 4.0.0
+ * JSON API-facing variant names generated for model schemas.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type VariantsJson = "json" | "jsonCreate" | "jsonUpdate"
 
@@ -57,9 +82,10 @@ export {
    *
    * It supports common variants for database and JSON apis.
    *
-   * @since 4.0.0
    * @category constructors
-   * @example
+   * @since 4.0.0
+   * **Example** (Defining a variant model class)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import { Model } from "effect/unstable/schema"
@@ -67,7 +93,7 @@ export {
    * export const GroupId = Schema.Number.pipe(Schema.brand("GroupId"))
    *
    * export class Group extends Model.Class<Group>("Group")({
-   *   id: Model.Generated(GroupId),
+   *   id: Model.GeneratedByDb(GroupId),
    *   name: Schema.String,
    *   createdAt: Model.DateTimeInsertFromDate,
    *   updatedAt: Model.DateTimeUpdateFromDate
@@ -97,63 +123,70 @@ export {
    */
   Class,
   /**
-   * @since 4.0.0
    * @category extraction
+   * @since 4.0.0
    */
   extract,
   /**
-   * @since 4.0.0
    * @category fields
+   * @since 4.0.0
    */
   Field,
   /**
-   * @since 4.0.0
    * @category fields
+   * @since 4.0.0
    */
   fieldEvolve,
   /**
-   * @since 4.0.0
    * @category fields
+   * @since 4.0.0
    */
   FieldExcept,
   /**
-   * @since 4.0.0
    * @category fields
+   * @since 4.0.0
    */
   FieldOnly,
   /**
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   Struct,
   /**
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   Union
 }
 
 /**
- * @since 4.0.0
+ * Returns the variant field definitions stored on a model or variant struct.
+ *
  * @category fields
+ * @since 4.0.0
  */
 export const fields: <A extends VariantSchema.Struct<any>>(self: A) => A[typeof VariantSchema.TypeId] =
   VariantSchema.fields
 
 /**
- * @since 4.0.0
+ * Marks a value as an explicit override for fields that otherwise use an
+ * overrideable default.
+ *
  * @category overrideable
+ * @since 4.0.0
  */
 export const Override: <A>(value: A) => A & Brand<"Override"> = VariantSchema.Override
 
 /**
- * @since 4.0.0
+ * Variant field type for a database-generated column that is present in select,
+ * update, and read JSON variants but omitted from insert variants.
+ *
  * @category generated
+ * @since 4.0.0
  */
-export interface Generated<S extends Schema.Top> extends
+export interface GeneratedByDb<S extends Schema.Top> extends
   VariantSchema.Field<{
     readonly select: S
-    readonly update: S
     readonly json: S
   }>
 {}
@@ -161,23 +194,26 @@ export interface Generated<S extends Schema.Top> extends
 /**
  * A field that represents a column that is generated by the database.
  *
- * It is available for selection and update, but not for insertion.
+ * It is available for reads only.
  *
- * @since 4.0.0
  * @category generated
+ * @since 4.0.0
  */
-export const Generated = <S extends Schema.Top>(
+export const GeneratedByDb = <S extends Schema.Top>(
   schema: S
-): Generated<S> =>
+): GeneratedByDb<S> =>
   Field({
     select: schema,
-    update: schema,
     json: schema
   })
 
 /**
- * @since 4.0.0
+ * Variant field type for an application-generated value that is present in
+ * database variants and read JSON, but omitted from JSON create and update
+ * variants.
+ *
  * @category generated
+ * @since 4.0.0
  */
 export interface GeneratedByApp<S extends Schema.Top> extends
   VariantSchema.Field<{
@@ -189,12 +225,13 @@ export interface GeneratedByApp<S extends Schema.Top> extends
 {}
 
 /**
- * A field that represents a column that is generated by the application.
+ * A field that represents a value generated by the application.
  *
- * It is required by the database, but not by the JSON variants.
+ * It is present in the database variants and read JSON variant, but omitted from
+ * the JSON create and update variants.
  *
- * @since 4.0.0
  * @category generated
+ * @since 4.0.0
  */
 export const GeneratedByApp = <S extends Schema.Top>(schema: S): GeneratedByApp<S> =>
   Field({
@@ -205,8 +242,11 @@ export const GeneratedByApp = <S extends Schema.Top>(schema: S): GeneratedByApp<
   })
 
 /**
- * @since 4.0.0
+ * Variant field type for a sensitive value that is available to database variants
+ * and omitted from all JSON variants.
+ *
  * @category sensitive
+ * @since 4.0.0
  */
 export interface Sensitive<S extends Schema.Top> extends
   VariantSchema.Field<{
@@ -220,8 +260,8 @@ export interface Sensitive<S extends Schema.Top> extends
  * A field that represents a sensitive value that should not be exposed in the
  * JSON variants.
  *
- * @since 4.0.0
  * @category sensitive
+ * @since 4.0.0
  */
 export const Sensitive = <S extends Schema.Top>(schema: S): Sensitive<S> =>
   Field({
@@ -231,16 +271,22 @@ export const Sensitive = <S extends Schema.Top>(schema: S): Sensitive<S> =>
   })
 
 /**
- * @since 4.0.0
+ * Schema type for an optional object key whose encoded value may be missing or
+ * null and whose decoded value is an `Option`.
+ *
  * @category optional
+ * @since 4.0.0
  */
 export interface optionalOption<S extends Schema.Top>
   extends Schema.decodeTo<Schema.Option<Schema.toType<S>>, Schema.optionalKey<Schema.NullOr<S>>>
 {}
 
 /**
- * @since 4.0.0
+ * Creates a schema for optional keys that decodes missing or null encoded values
+ * through `Option` and encodes `Option` values back to optional nullable keys.
+ *
  * @category optional
+ * @since 4.0.0
  */
 export const optionalOption = <S extends Schema.Top>(schema: S): optionalOption<S> =>
   Schema.optionalKey(Schema.NullOr(schema)).pipe(
@@ -259,8 +305,8 @@ export const optionalOption = <S extends Schema.Top>(schema: S): optionalOption<
  * For the database variants, it will accept `null`able values.
  * For the JSON variants, it will also accept missing keys.
  *
- * @since 4.0.0
  * @category optional
+ * @since 4.0.0
  */
 export interface FieldOption<S extends Schema.Top> extends
   VariantSchema.Field<{
@@ -279,8 +325,8 @@ export interface FieldOption<S extends Schema.Top> extends
  * For the database variants, it will accept `null`able values.
  * For the JSON variants, it will also accept missing keys.
  *
- * @since 4.0.0
  * @category optional
+ * @since 4.0.0
  */
 export const FieldOption: <Field extends VariantSchema.Field<any> | Schema.Top>(
   self: Field
@@ -302,8 +348,11 @@ export const FieldOption: <Field extends VariantSchema.Field<any> | Schema.Top>(
   }) as any
 
 /**
- * @since 4.0.0
+ * Variant field type for SQLite booleans stored as `0 | 1` in database variants
+ * and exposed as `boolean` in JSON variants.
+ *
  * @category booleans
+ * @since 4.0.0
  */
 export interface BooleanSqlite extends
   VariantSchema.Field<{
@@ -320,8 +369,8 @@ export interface BooleanSqlite extends
  * A schema for sqlite booleans that are represented as `0 | 1` in database
  * variants and `boolean` in JSON variants.
  *
- * @since 4.0.0
  * @category booleans
+ * @since 4.0.0
  */
 export const BooleanSqlite: BooleanSqlite = Field({
   select: Schema.BooleanFromBit,
@@ -333,8 +382,11 @@ export const BooleanSqlite: BooleanSqlite = Field({
 })
 
 /**
- * @since 4.0.0
+ * Schema type for a `DateTime.Utc` date-only value encoded as a `YYYY-MM-DD`
+ * string.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export interface Date extends Schema.decodeTo<Schema.instanceOf<DateTime.Utc>, Schema.String> {}
 
@@ -342,8 +394,8 @@ export interface Date extends Schema.decodeTo<Schema.instanceOf<DateTime.Utc>, S
  * A schema for a `DateTime.Utc` that is serialized as a date string in the
  * format `YYYY-MM-DD`.
  *
- * @since 4.0.0
  * @category date & time
+ * @since 4.0.0
  */
 export const Date: Date = Schema.String.pipe(
   Schema.decodeTo(Schema.DateTimeUtc, {
@@ -353,40 +405,55 @@ export const Date: Date = Schema.String.pipe(
 )
 
 /**
- * @since 4.0.0
+ * Overrideable date-only UTC schema whose constructor default is the current date
+ * with the time component removed.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export const DateWithNow = VariantSchema.Overrideable(Date, {
   defaultValue: Effect.map(DateTime.now, DateTime.removeTime)
 })
 
 /**
- * @since 4.0.0
+ * Overrideable UTC date-time schema encoded as a string, with a constructor
+ * default of the current `DateTime.Utc`.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeWithNow = VariantSchema.Overrideable(Schema.DateTimeUtcFromString, {
   defaultValue: DateTime.now
 })
 
 /**
- * @since 4.0.0
+ * Overrideable UTC date-time schema encoded as a JavaScript `Date`, with a
+ * constructor default of the current `DateTime.Utc`.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeFromDateWithNow = VariantSchema.Overrideable(Schema.DateTimeUtcFromDate, {
   defaultValue: DateTime.now
 })
 
 /**
- * @since 4.0.0
+ * Overrideable UTC date-time schema encoded as milliseconds, with a constructor
+ * default of the current `DateTime.Utc`.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeFromNumberWithNow = VariantSchema.Overrideable(Schema.DateTimeUtcFromMillis, {
   defaultValue: DateTime.now
 })
 
 /**
- * @since 4.0.0
+ * Variant field type for a UTC date-time stored as a string, defaulted to the
+ * current time on insert, available for selection, and omitted from updates.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export interface DateTimeInsert extends
   VariantSchema.Field<{
@@ -402,8 +469,8 @@ export interface DateTimeInsert extends
  *
  * It is omitted from updates and is available for selection.
  *
- * @since 4.0.0
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeInsert: DateTimeInsert = Field({
   select: Schema.DateTimeUtcFromString,
@@ -412,8 +479,11 @@ export const DateTimeInsert: DateTimeInsert = Field({
 })
 
 /**
- * @since 4.0.0
+ * Variant field type for a UTC date-time stored as a JavaScript `Date` in
+ * database variants, encoded as a string for JSON, and defaulted on insert.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export interface DateTimeInsertFromDate extends
   VariantSchema.Field<{
@@ -429,8 +499,8 @@ export interface DateTimeInsertFromDate extends
  *
  * It is omitted from updates and is available for selection.
  *
- * @since 4.0.0
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeInsertFromDate: DateTimeInsertFromDate = Field({
   select: Schema.DateTimeUtcFromDate,
@@ -439,8 +509,11 @@ export const DateTimeInsertFromDate: DateTimeInsertFromDate = Field({
 })
 
 /**
- * @since 4.0.0
+ * Variant field type for a UTC date-time encoded as milliseconds and defaulted to
+ * the current time on insert.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export interface DateTimeInsertFromNumber extends
   VariantSchema.Field<{
@@ -456,8 +529,8 @@ export interface DateTimeInsertFromNumber extends
  *
  * It is omitted from updates and is available for selection.
  *
- * @since 4.0.0
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeInsertFromNumber: DateTimeInsertFromNumber = Field({
   select: Schema.DateTimeUtcFromMillis,
@@ -466,8 +539,11 @@ export const DateTimeInsertFromNumber: DateTimeInsertFromNumber = Field({
 })
 
 /**
- * @since 4.0.0
+ * Variant field type for a UTC date-time stored as a string and defaulted to the
+ * current time on both inserts and updates.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export interface DateTimeUpdate extends
   VariantSchema.Field<{
@@ -485,8 +561,8 @@ export interface DateTimeUpdate extends
  * It is set to the current `DateTime.Utc` on updates and inserts and is
  * available for selection.
  *
- * @since 4.0.0
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeUpdate: DateTimeUpdate = Field({
   select: Schema.DateTimeUtcFromString,
@@ -496,8 +572,12 @@ export const DateTimeUpdate: DateTimeUpdate = Field({
 })
 
 /**
- * @since 4.0.0
+ * Variant field type for a UTC date-time stored as a JavaScript `Date` in
+ * database variants, encoded as a string for JSON, and defaulted on inserts and
+ * updates.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export interface DateTimeUpdateFromDate extends
   VariantSchema.Field<{
@@ -515,8 +595,8 @@ export interface DateTimeUpdateFromDate extends
  * It is set to the current `DateTime.Utc` on updates and inserts and is
  * available for selection.
  *
- * @since 4.0.0
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeUpdateFromDate: DateTimeUpdateFromDate = Field({
   select: Schema.DateTimeUtcFromDate,
@@ -526,8 +606,11 @@ export const DateTimeUpdateFromDate: DateTimeUpdateFromDate = Field({
 })
 
 /**
- * @since 4.0.0
+ * Variant field type for a UTC date-time encoded as milliseconds and defaulted to
+ * the current time on both inserts and updates.
+ *
  * @category date & time
+ * @since 4.0.0
  */
 export interface DateTimeUpdateFromNumber extends
   VariantSchema.Field<{
@@ -545,8 +628,8 @@ export interface DateTimeUpdateFromNumber extends
  * It is set to the current `DateTime.Utc` on updates and inserts and is
  * available for selection.
  *
- * @since 4.0.0
  * @category date & time
+ * @since 4.0.0
  */
 export const DateTimeUpdateFromNumber: DateTimeUpdateFromNumber = Field({
   select: Schema.DateTimeUtcFromMillis,
@@ -556,8 +639,11 @@ export const DateTimeUpdateFromNumber: DateTimeUpdateFromNumber = Field({
 })
 
 /**
- * @since 4.0.0
+ * Variant field type for a JSON value stored as text in database variants and
+ * exposed through the supplied schema in JSON variants.
+ *
  * @category json
+ * @since 4.0.0
  */
 export interface JsonFromString<S extends Schema.Top> extends
   VariantSchema.Field<{
@@ -575,8 +661,8 @@ export interface JsonFromString<S extends Schema.Top> extends
  *
  * The "json" variants will use the object schema directly.
  *
- * @since 4.0.0
  * @category json
+ * @since 4.0.0
  */
 export const JsonFromString = <S extends Schema.Top>(
   schema: S
@@ -593,10 +679,13 @@ export const JsonFromString = <S extends Schema.Top>(
 }
 
 /**
- * @since 4.0.0
+ * Variant field type for a branded binary UUID v4 value whose insert variant
+ * generates a UUID by default.
+ *
  * @category uuid
+ * @since 4.0.0
  */
-export interface UuidV4Insert<B extends string> extends
+export interface UuidV4BytesInsert<B extends string> extends
   VariantSchema.Field<{
     readonly select: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>
     readonly insert: Schema.withConstructorDefault<Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>>
@@ -606,18 +695,23 @@ export interface UuidV4Insert<B extends string> extends
 {}
 
 /**
- * @since 4.0.0
+ * Schema for binary `Uint8Array` values backed by an `ArrayBuffer`.
+ *
  * @category Uint8Array
+ * @since 4.0.0
  */
 export const Uint8Array: Schema.instanceOf<Uint8Array<ArrayBuffer>> = Schema.Uint8Array as Schema.instanceOf<
   globalThis.Uint8Array<ArrayBuffer>
 >
 
 /**
- * @since 4.0.0
+ * Adds a constructor default that generates a binary UUID v4 for a branded
+ * `Uint8Array` schema.
+ *
  * @category uuid
+ * @since 4.0.0
  */
-export const UuidV4WithGenerate = <B extends string>(
+export const UuidV4BytesWithGenerate = <B extends string>(
   schema: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>
 ): Schema.withConstructorDefault<Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>> =>
   schema.pipe(Schema.withConstructorDefault(Effect.sync(() => Uuid.v4({}, new globalThis.Uint8Array(16)))))
@@ -625,11 +719,54 @@ export const UuidV4WithGenerate = <B extends string>(
 /**
  * A field that represents a binary UUID v4 that is generated on inserts.
  *
+ * @category uuid
  * @since 4.0.0
+ */
+export const UuidV4BytesInsert = <const B extends string>(
+  schema: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>
+): UuidV4BytesInsert<B> =>
+  Field({
+    select: schema,
+    insert: UuidV4BytesWithGenerate(schema),
+    update: schema,
+    json: schema
+  })
+
+/**
+ * Variant field type for a branded string UUID v4 value whose insert variant
+ * generates a UUID by default.
+ *
+ * @category uuid
+ * @since 4.0.0
+ */
+export interface UuidV4Insert<B extends string> extends
+  VariantSchema.Field<{
+    readonly select: Schema.brand<Schema.String, B>
+    readonly insert: Schema.withConstructorDefault<Schema.brand<Schema.String, B>>
+    readonly update: Schema.brand<Schema.String, B>
+    readonly json: Schema.brand<Schema.String, B>
+  }>
+{}
+
+/**
+ * Adds a constructor default that generates a string UUID v4.
+ *
  * @category uuid
+ * @since 4.0.0
+ */
+export const UuidV4WithGenerate = <B extends string>(
+  schema: Schema.brand<Schema.String, B>
+): Schema.withConstructorDefault<Schema.brand<Schema.String, B>> =>
+  schema.pipe(Schema.withConstructorDefault(Effect.sync(() => Uuid.v4())))
+
+/**
+ * A field that represents a string UUID v4 that is generated on inserts.
+ *
+ * @category uuid
+ * @since 4.0.0
  */
 export const UuidV4Insert = <const B extends string>(
-  schema: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>
+  schema: Schema.brand<Schema.String, B>
 ): UuidV4Insert<B> =>
   Field({
     select: schema,
@@ -637,3 +774,50 @@ export const UuidV4Insert = <const B extends string>(
     update: schema,
     json: schema
   })
+
+/**
+ * Variant field type for a branded string UUID v7 value whose insert variant
+ * generates a UUID by default.
+ *
+ * @category uuid
+ * @since 4.0.0
+ */
+export interface UuidV7Insert<B extends string> extends
+  VariantSchema.Field<{
+    readonly select: Schema.brand<Schema.String, B>
+    readonly insert: Schema.withConstructorDefault<Schema.brand<Schema.String, B>>
+    readonly update: Schema.brand<Schema.String, B>
+    readonly json: Schema.brand<Schema.String, B>
+  }>
+{}
+
+/**
+ * Adds a constructor default that generates a string UUID v7.
+ *
+ * @category uuid
+ * @since 4.0.0
+ */
+export const UuidV7WithGenerate = <B extends string>(
+  schema: Schema.brand<Schema.String, B>
+): Schema.withConstructorDefault<Schema.brand<Schema.String, B>> =>
+  schema.pipe(Schema.withConstructorDefault(Effect.clockWith((clock) =>
+    Effect.succeed(Uuid.v7({
+      msecs: clock.currentTimeMillisUnsafe()
+    }))
+  )))
+
+/**
+ * A field that represents a string UUID v7 that is generated on inserts.
+ *
+ * @category uuid
+ * @since 4.0.0
+ */
+export const UuidV7Insert = <const B extends string>(
+  schema: Schema.brand<Schema.String, B>
+): UuidV7Insert<B> =>
+  Field({
+    select: schema,
+    insert: UuidV7WithGenerate(schema),
+    update: schema,
+    json: schema
+  })