effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/rpc/RpcWorker.ts

@@ -1,4 +1,21 @@
 /**
+ * Helpers for passing a schema-encoded bootstrap message to worker-backed RPC
+ * protocols.
+ *
+ * Worker RPC protocols can send one initial message when each worker starts,
+ * before ordinary RPC requests begin flowing. Use this module to build and
+ * provide that message from the client side, and to decode it inside the
+ * worker-side server. Common payloads include per-worker configuration,
+ * credentials or session metadata, feature flags, preloaded data, or
+ * transferable resources such as `ArrayBuffer` and `MessagePort` values.
+ *
+ * The initial message uses the supplied schema's JSON codec and is posted as a
+ * worker message, so it is separate from the normal `RpcSerialization` used for
+ * RPC request and response traffic. Values still need to be valid for the
+ * worker transport's structured clone boundary. Transferable annotations can
+ * collect objects for the `postMessage` transfer list, but transferring moves
+ * ownership to the worker and may detach buffers from the sender.
+ *
  * @since 4.0.0
  */
 import type { NoSuchElementError } from "../../Cause.ts"
@@ -10,8 +27,11 @@ import * as Transferable from "../workers/Transferable.ts"
 import type { Protocol } from "./RpcServer.ts"
 
 /**
- * @since 4.0.0
+ * Context service that supplies the initial RPC worker message as encoded data
+ * paired with any transferables that should be posted with it.
+ *
  * @category initial message
+ * @since 4.0.0
  */
 export class InitialMessage extends Context.Service<
   InitialMessage,
@@ -24,13 +44,18 @@ export class InitialMessage extends Context.Service<
 >()("effect/rpc/RpcWorker/InitialMessage") {}
 
 /**
- * @since 4.0.0
+ * Types related to the encoded initial message exchanged with an RPC worker.
+ *
  * @category initial message
+ * @since 4.0.0
  */
 export declare namespace InitialMessage {
   /**
-   * @since 4.0.0
+   * Tagged wire representation of an RPC worker initial message after schema
+   * encoding.
+   *
    * @category initial message
+   * @since 4.0.0
    */
   export interface Encoded {
     readonly _tag: "InitialMessage"
@@ -41,8 +66,11 @@ export declare namespace InitialMessage {
 const ProtocolTag: typeof Protocol = Context.Service("@effect/rpc/RpcServer/Protocol") as any
 
 /**
- * @since 4.0.0
+ * Runs an effect, encodes its result with the schema's JSON codec, and returns
+ * the encoded value together with collected transferables.
+ *
  * @category initial message
+ * @since 4.0.0
  */
 export const makeInitialMessage = <S extends Schema.Top, E, R2>(
   schema: S,
@@ -63,8 +91,11 @@ export const makeInitialMessage = <S extends Schema.Top, E, R2>(
 }
 
 /**
- * @since 4.0.0
+ * Provides the `InitialMessage` service from a schema and build effect,
+ * capturing the layer context and dying if schema encoding fails.
+ *
  * @category initial message
+ * @since 4.0.0
  */
 export const layerInitialMessage = <S extends Schema.Top, R2>(
   schema: S,
@@ -79,14 +110,17 @@ export const layerInitialMessage = <S extends Schema.Top, R2>(
   )
 
 /**
- * @since 4.0.0
+ * Reads the protocol initial message and decodes it with the supplied schema,
+ * failing if no initial message is available or decoding fails.
+ *
  * @category initial message
+ * @since 4.0.0
  */
 export const initialMessage = <S extends Schema.Top>(
   schema: S
 ): Effect.Effect<S["Type"], NoSuchElementError | Schema.SchemaError, Protocol | S["DecodingServices"]> =>
-  ProtocolTag.asEffect().pipe(
+  ProtocolTag.pipe(
     Effect.flatMap((protocol) => protocol.initialMessage),
-    Effect.flatMap((o) => o.asEffect()),
+    Effect.flatMap(Effect.fromOption),
     Effect.flatMap(Schema.decodeUnknownEffect(Schema.toCodecJson(schema)))
   )

package/src/unstable/rpc/Utils.ts

@@ -1,4 +1,27 @@
 /**
+ * Internal helpers for constructing RPC protocol services whose receive loop is
+ * installed separately from the operations that write to it.
+ *
+ * This module is used by the client and server `Protocol.make` constructors to
+ * let transports expose a stable service immediately while buffering messages
+ * until the protocol's `run` method has installed the active receiver. Buffered
+ * writes keep the `Context` that was current at the time of the write, so
+ * replaying early messages preserves fiber-local services such as tracing or
+ * request metadata.
+ *
+ * The general `withRun` helper is for single receive-loop services, such as
+ * server transports, while `withRunClient` specializes the same pattern for
+ * client transports by tracking active client ids and keeping a separate buffer
+ * per client. They are most useful when implementing custom RPC transports or
+ * test protocols that need to send before the consumer fiber has started.
+ *
+ * These helpers intentionally work on `Omit<Service, "run">` and re-add `run`
+ * so generated `Context.Service` static `make` members can preserve their
+ * exact service shape. When using them from generated or type-helper-heavy
+ * protocol code, keep the `run` signature aligned with the target service:
+ * the server helper has one shared writer, but the client helper requires a
+ * `clientId` because responses and buffered messages are routed per client.
+ *
  * @since 4.0.0
  */
 import type * as Context from "../../Context.ts"
@@ -8,6 +31,10 @@ import type { Protocol } from "./RpcClient.ts"
 import type { FromServerEncoded } from "./RpcMessage.ts"
 
 /**
+ * Builds a service with a `run` method that buffers writes until `run` installs
+ * a writer, replays buffered writes with their original contexts, and restores
+ * the previous writer when the run ends.
+ *
  * @since 4.0.0
  */
 export const withRun = <
@@ -46,6 +73,10 @@ export const withRun = <
   })
 
 /**
+ * Builds an RPC client protocol service that tracks active client IDs and
+ * buffers server responses per client until that client's `run` handler is
+ * installed.
+ *
  * @since 4.0.0
  */
 export const withRunClient = <EX, RX>(

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"
@@ -97,58 +123,66 @@ 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
   VariantSchema.Field<{
@@ -163,8 +197,8 @@ export interface Generated<S extends Schema.Top> extends
  *
  * It is available for selection and update, but not for insertion.
  *
- * @since 4.0.0
  * @category generated
+ * @since 4.0.0
  */
 export const Generated = <S extends Schema.Top>(
   schema: S
@@ -176,8 +210,12 @@ export const Generated = <S extends Schema.Top>(
   })
 
 /**
- * @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 +227,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 +244,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 +262,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 +273,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 +307,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 +327,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 +350,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 +371,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 +384,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 +396,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 +407,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 +471,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 +481,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 +501,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 +511,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 +531,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 +541,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 +563,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 +574,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 +597,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 +608,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 +630,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 +641,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 +663,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,8 +681,11 @@ 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
   VariantSchema.Field<{
@@ -606,16 +697,21 @@ 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>(
   schema: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>
@@ -625,8 +721,8 @@ export const UuidV4WithGenerate = <B extends string>(
 /**
  * A field that represents a binary UUID v4 that is generated on inserts.
  *
- * @since 4.0.0
  * @category uuid
+ * @since 4.0.0
  */
 export const UuidV4Insert = <const B extends string>(
   schema: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>