effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/LayerMap.ts

@@ -33,7 +33,7 @@ type IdleTimeToLiveInput<K> = Duration.Input | ((key: K) => Duration.Input)
  *
  * **Example** (Managing keyed layers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, LayerMap } from "effect"
  *
  * // Define a service key
@@ -53,14 +53,22 @@ type IdleTimeToLiveInput<K> = Duration.Input | ((key: K) => Duration.Input)
  *   const layerMap = yield* createDatabaseLayerMap
  *
  *   // Get a layer for a specific environment
- *   const devLayer = layerMap.get("development")
+ *   const development = yield* Effect.provide(
+ *     DatabaseService.use((database) => database.query("SELECT 1")),
+ *     layerMap.get("development")
+ *   )
  *
  *   // Get context directly
- *   const context = yield* layerMap.contextEffect("production")
+ *   const productionContext = yield* layerMap.contextEffect("production")
+ *   const production = yield* Context.get(productionContext, DatabaseService).query("SELECT 1")
  *
  *   // Invalidate a cached layer
  *   yield* layerMap.invalidate("development")
+ *
+ *   return { development, production }
  * })
+ *
+ * await Effect.runPromise(Effect.scoped(program)) // => { development: "development: SELECT 1", production: "production: SELECT 1" }
  * ```
  *
  * @category models
@@ -95,7 +103,7 @@ export interface LayerMap<in out K, in out I, in out E = never> {
  *
  * **Example** (Creating a layer map)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, LayerMap } from "effect"
  *
  * // Define a service key
@@ -117,16 +125,16 @@ export interface LayerMap<in out K, in out I, in out E = never> {
  *   const devLayer = layerMap.get("development")
  *
  *   // Use the layer to provide the service
- *   const result = yield* Effect.provide(
+ *   return yield* Effect.provide(
  *     Effect.gen(function*() {
  *       const db = yield* DatabaseService
  *       return yield* db.query("SELECT * FROM users")
  *     }),
  *     devLayer
  *   )
- *
- *   console.log(result) // "development: SELECT * FROM users"
  * })
+ *
+ * await Effect.runPromise(Effect.scoped(program)) // => "development: SELECT * FROM users"
  * ```
  *
  * @category constructors
@@ -150,6 +158,7 @@ export const make: <
   lookup: (key: K) => Layer.Layer<I, EL, RL>,
   options?: {
     readonly idleTimeToLive?: IdleTimeToLiveInput<K> | undefined
+    readonly preloadKeys?: Iterable<K> | undefined
   } | undefined
 ) {
   const context = yield* Effect.context<never>()
@@ -163,6 +172,12 @@ export const make: <
     idleTimeToLive: options?.idleTimeToLive
   })
 
+  if (options?.preloadKeys) {
+    for (const key of options.preloadKeys) {
+      yield* Effect.scoped(RcMap.get(rcMap, key))
+    }
+  }
+
   return identity<LayerMap<K, I, any>>({
     [TypeId]: TypeId,
     rcMap,
@@ -182,24 +197,20 @@ export const make: <
  *
  * **Example** (Creating a layer map from a record)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, LayerMap } from "effect"
  *
- * // Define service keys
- * const DevDatabase = Context.Service<{
- *   readonly query: (sql: string) => Effect.Effect<string>
- * }>("DevDatabase")
- *
- * const ProdDatabase = Context.Service<{
+ * // Define a service key
+ * const Database = Context.Service<{
  *   readonly query: (sql: string) => Effect.Effect<string>
- * }>("ProdDatabase")
+ * }>("Database")
  *
  * // Create predefined layers
  * const layers = {
- *   development: Layer.succeed(DevDatabase)({
+ *   development: Layer.succeed(Database)({
  *     query: Effect.fn("DevDatabase.query")((sql) => Effect.succeed(`DEV: ${sql}`))
  *   }),
- *   production: Layer.succeed(ProdDatabase)({
+ *   production: Layer.succeed(Database)({
  *     query: Effect.fn("ProdDatabase.query")((sql) => Effect.succeed(`PROD: ${sql}`))
  *   })
  * } as const
@@ -210,12 +221,19 @@ export const make: <
  *     idleTimeToLive: "10 seconds"
  *   })
  *
- *   // Get layers by key
- *   const devLayer = layerMap.get("development")
- *   const prodLayer = layerMap.get("production")
+ *   const development = yield* Effect.provide(
+ *     Database.use((database) => database.query("SELECT 1")),
+ *     layerMap.get("development")
+ *   )
+ *   const production = yield* Effect.provide(
+ *     Database.use((database) => database.query("SELECT 1")),
+ *     layerMap.get("production")
+ *   )
  *
- *   console.log("LayerMap created from record")
+ *   return { development, production }
  * })
+ *
+ * await Effect.runPromise(Effect.scoped(program)) // => { development: "DEV: SELECT 1", production: "PROD: SELECT 1" }
  * ```
  *
  * @category constructors
@@ -310,8 +328,8 @@ export interface TagClass<
  *
  * **Example** (Defining a layer map service)
  *
- * ```ts
- * import { Console, Context, Effect, Layer, LayerMap } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Layer, LayerMap } from "effect"
  *
  * // Define a service key
  * const Greeter = Context.Service<{
@@ -334,7 +352,7 @@ export interface TagClass<
  * const program = Effect.gen(function*() {
  *   // Access and use the Greeter service
  *   const greeter = yield* Greeter
- *   yield* Console.log(yield* greeter.greet)
+ *   return yield* greeter.greet
  * }).pipe(
  *   // Use the GreeterMap service to provide a variant of the Greeter service
  *   Effect.provide(GreeterMap.get("John"))
@@ -342,6 +360,8 @@ export interface TagClass<
  *   // Provide the GreeterMap layer
  *   Effect.provide(GreeterMap.layer)
  * )
+ *
+ * await Effect.runPromise(program) // => "Hello, John!"
  * ```
  *
  * @category services
@@ -424,7 +444,7 @@ export declare namespace Service {
   /**
    * Extracts the key type accepted by a `LayerMap.Service` definition.
    *
-   * @category services
+   * @category utility types
    * @since 3.14.0
    */
   export type Key<Options> = Options extends { readonly lookup: (key: infer K) => any } ? K
@@ -434,7 +454,7 @@ export declare namespace Service {
   /**
    * Extracts the layer type produced by a `LayerMap.Service` definition.
    *
-   * @category services
+   * @category utility types
    * @since 3.14.0
    */
   export type Layers<Options> = Options extends { readonly lookup: (key: infer _K) => infer Layers } ? Layers
@@ -445,7 +465,7 @@ export declare namespace Service {
    * Extracts the services provided by the layers in a `LayerMap.Service`
    * definition.
    *
-   * @category services
+   * @category utility types
    * @since 3.14.0
    */
   export type Success<Options> = Layers<Options> extends Layer.Layer<infer _A, infer _E, infer _R> ? _A : never
@@ -453,7 +473,7 @@ export declare namespace Service {
   /**
    * Extracts the error type of the layers in a `LayerMap.Service` definition.
    *
-   * @category services
+   * @category utility types
    * @since 3.14.0
    */
   export type Error<Options> = Layers<Options> extends Layer.Layer<infer _A, infer _E, infer _R> ? _E : never
@@ -462,7 +482,7 @@ export declare namespace Service {
    * Extracts the service requirements of the layers in a `LayerMap.Service`
    * definition.
    *
-   * @category services
+   * @category utility types
    * @since 4.0.0
    */
   export type Services<Options> = Layers<Options> extends Layer.Layer<infer _A, infer _E, infer _R> ? _R : never

package/src/LayerRef.ts

@@ -92,7 +92,7 @@ export interface LayerRef<in out I, in out E = never> {
  *
  * **Example** (Sharing one layer-built service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, LayerRef } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -121,6 +121,8 @@ export interface LayerRef<in out I, in out E = never> {
  *     return result
  *   })
  * )
+ *
+ * await Effect.runPromise(program) // => "result"
  * ```
  *
  * @see {@link Service} for defining a reusable service class around a `LayerRef`
@@ -270,7 +272,7 @@ export interface TagClass<
  *
  * **Example** (Defining a refreshable service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, LayerRef } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -293,6 +295,8 @@ export interface TagClass<
  *   Effect.provide(DatabaseRef.get),
  *   Effect.provide(DatabaseRef.layer)
  * )
+ *
+ * await Effect.runPromise(program) // => "result"
  * ```
  *
  * @see {@link make} for creating a `LayerRef` value without defining a service class