Effect Usage Report.md

Effect API Usage Report

Generated on: 2025-06-20

Executive Summary

This report provides a comprehensive analysis of Effect-TS API usage in the project.

Key Statistics

• Total Unique Effect APIs Used: 121
• Total API Calls: 1,548
• Most Used Module: Schema (716 calls, 46.3% of total)
• Most Used Single API: Schema.String (175 calls)
• Primary Usage Location: Backend services (cluster/ directory)

API Usage by Module

1. Effect Core Module (511 calls, 31 unique APIs)

API	Count	Usage Pattern
Effect.gen	130	Generator-based effect composition
Effect.logInfo	73	Information logging
Effect.tryPromise	55	Converting promises to effects
Effect.fail	35	Creating failure effects
Effect.catchAll	22	Catching all errors
Effect.succeed	20	Creating success effects
Effect.runFork	20	Background execution
Effect.provide	20	Providing dependencies
Effect.Service	15	Service definition
Effect.orDie	14	Converting to defects
Effect.catchTag	14	Catching specific errors
Effect.void	13	Discarding values
Effect.addFinalizer	11	Resource cleanup
Effect.andThen	10	Sequential composition
Effect.tapError	10	Error inspection
Effect.runPromise	8	Running as promise
Effect.acquireRelease	6	Resource acquisition
Effect.sleep	5	Delays
Effect.scoped	4	Scoped resources
Effect.map	4	Value transformation
Effect.flatMap	3	Chaining effects
Effect.all	3	Parallel execution
Effect.logError	3	Error logging
Effect.logDebug	2	Debug logging
Effect.logWarning	2	Warning logging
Effect.tapBoth	2	Inspecting both cases
Effect.retry	2	Retry logic
Effect.sync	2	Synchronous effects
Effect.if	1	Conditional effects
Effect.forEach	1	Iteration
Effect.runSync	1	Synchronous execution

2. Schema Module (716 calls, 31 unique APIs)

API	Count	Usage Pattern
Schema.String	175	String type definition
Schema.optional	102	Optional fields
Schema.Struct	91	Object schemas
Schema.Number	81	Number type definition
Schema.Schema	60	Type references
Schema.TaggedError	38	Tagged error types
Schema.Literal	29	Literal values
Schema.annotations	29	Metadata (HTTP status)
Schema.Array	19	Array schemas
Schema.fromBrand	15	Branded types
Schema.asserts	10	Schema assertions
Schema.Unknown	10	Unknown type
Schema.int	8	Integer constraint
Schema.Class	7	Class-based schemas
Schema.DateTimeUtc	6	DateTime schemas
Schema.Boolean	5	Boolean type
Schema.maxItems	4	Array size constraint
Schema.enum	4	Enum definitions
Schema.Record	3	Record schemas
Schema.minLength	3	String length constraint
Schema.NumberFromString	2	Type conversion
Schema.nullable	2	Nullable types
Schema.positive	2	Positive number constraint
Schema.maxLength	2	String length constraints
Schema.minItems	2	Array size constraints
Schema.standardSchemaV1	2	Standard schema generation
Schema.BooleanFromString	1	Type conversion
Schema.UUID	1	UUID schema
Schema.ULID	1	ULID schema
Schema.withDefault	1	Default values
Schema.transform	1	Custom transformations

3. Layer Module (59 calls, 8 unique APIs)

API	Count	Usage Pattern
Layer.provide	25	Layer composition
Layer.make	18	Layer construction
Layer.succeed	8	Success layers
Layer.effect	4	Effect-based layers
Layer.empty	1	Empty layer
Layer.provideMerge	1	Provide and merge
Layer.merge	1	Layer merging
Layer.tap	1	Layer inspection

4. State Management APIs (73 calls, 13 unique APIs)

Ref (Mutable References)

API	Count	Usage Pattern
Ref.update	20	State updates
Ref.get	17	Reading state
Ref.make	6	Creating refs
Ref.updateAndGet	1	Update and return
Ref.set	1	Setting values

Queue (Message Queues)

API	Count	Usage Pattern
Queue.offer	20	Adding to queue
Queue.unbounded	1	Creating unbounded queue

PubSub (Publish/Subscribe)

API	Count	Usage Pattern
PubSub.sliding	1	Sliding window pubsub
PubSub.publish	1	Publishing messages
PubSub.subscribe	1	Subscribing to messages

Latch (Synchronization)

API	Count	Usage Pattern
Latch.open	2	Opening latch
Latch.await	1	Waiting on latch
Latch.make	1	Creating latch

5. HTTP APIs (@effect/platform) (66 calls, 11 unique APIs)

API	Count	Usage Pattern
HttpApiSchema.annotations	29	HTTP metadata
HttpApiEndpoint.post	12	POST endpoints
HttpApiGroup.make	7	API groups
HttpApiBuilder.group	7	Building groups
HttpApiEndpoint.get	4	GET endpoints
HttpServerResponse.text	2	Text responses
HttpApiEndpoint.put	1	PUT endpoints
HttpApiBuilder.serve	1	Serving APIs
HttpApiBuilder.api	1	API construction
HttpServer.withLogAddress	1	Server logging
HttpServerResponse.stream	1	Stream responses

6. Configuration & Infrastructure (28 calls, 8 unique APIs)

API	Count	Usage Pattern
Config.bucketName	9	S3 bucket config
Config.region	5	AWS region config
Config.string	4	String configs
Config.redacted	3	Sensitive configs
Config.boolean	1	Boolean configs
Logger.withMinimumLogLevel	2	Log level config
Logger.pretty	2	Pretty logging
LogLevel.Info	2	Log level setting

7. HashMap Module (51 calls, 4 unique APIs)

API	Count	Usage Pattern
HashMap.get	18	Getting values
HashMap.set	14	Setting values
HashMap.remove	10	Removing values
HashMap.empty	9	Empty maps

8. Option Module (15 calls, 3 unique APIs)

API	Count	Usage Pattern
Option.isNone	8	Checking empty
Option.isSome	6	Checking presence
Option.getOrElse	1	Default extraction

9. Other Utility APIs (29 calls, 12 unique APIs)

API	Count	Usage Pattern
Brand.nominal	9	Branded types
DateTime.unsafeNow	3	Current time
Redacted.make	3	Creating redacted
Redacted.value	2	Accessing redacted
Exit.void	2	Void exits (scope cleanup)
CloseableScope	2	Closeable scope types
Scope.close	2	Scope cleanup
Fiber.value	2	Fiber results
Duration.millis	1	Time durations
Schedule.spaced	1	Scheduling
Scope.make	1	Scope creation
Fiber.get	1	Fiber access

{
  "metadata": {
    "generatedOn": "2025-06-20",
    "totalUniqueAPIs": 121,
    "totalAPICalls": 1548,
    "primaryUsageLocation": "cluster/"
  },
  "apiUsage": {
    "effect": {
      "totalCalls": 511,
      "uniqueAPIs": 31,
      "apis": [
        { "name": "Effect.gen", "count": 130, "category": "composition" },
        { "name": "Effect.logInfo", "count": 73, "category": "logging" },
        { "name": "Effect.tryPromise", "count": 55, "category": "interop" },
        { "name": "Effect.fail", "count": 35, "category": "error" },
        { "name": "Effect.catchAll", "count": 22, "category": "error" },
        { "name": "Effect.succeed", "count": 20, "category": "construction" },
        { "name": "Effect.runFork", "count": 20, "category": "execution" },
        { "name": "Effect.provide", "count": 20, "category": "dependency" },
        { "name": "Effect.Service", "count": 15, "category": "service" },
        { "name": "Effect.orDie", "count": 14, "category": "error" },
        { "name": "Effect.catchTag", "count": 14, "category": "error" },
        { "name": "Effect.void", "count": 13, "category": "transformation" },
        { "name": "Effect.addFinalizer", "count": 11, "category": "resource" },
        { "name": "Effect.andThen", "count": 10, "category": "composition" },
        { "name": "Effect.tapError", "count": 10, "category": "inspection" },
        { "name": "Effect.runPromise", "count": 8, "category": "execution" },
        { "name": "Effect.acquireRelease", "count": 6, "category": "resource" },
        { "name": "Effect.sleep", "count": 5, "category": "timing" },
        { "name": "Effect.scoped", "count": 4, "category": "resource" },
        { "name": "Effect.map", "count": 4, "category": "transformation" },
        { "name": "Effect.flatMap", "count": 3, "category": "composition" },
        { "name": "Effect.all", "count": 3, "category": "parallel" },
        { "name": "Effect.logError", "count": 3, "category": "logging" },
        { "name": "Effect.logDebug", "count": 2, "category": "logging" },
        { "name": "Effect.logWarning", "count": 2, "category": "logging" },
        { "name": "Effect.tapBoth", "count": 2, "category": "inspection" },
        { "name": "Effect.retry", "count": 2, "category": "resilience" },
        { "name": "Effect.sync", "count": 2, "category": "construction" },
        { "name": "Effect.if", "count": 1, "category": "control" },
        { "name": "Effect.forEach", "count": 1, "category": "iteration" },
        { "name": "Effect.runSync", "count": 1, "category": "execution" }
      ]
    },
    "schema": {
      "totalCalls": 716,
      "uniqueAPIs": 31,
      "apis": [
        { "name": "Schema.String", "count": 175, "category": "primitive" },
        { "name": "Schema.optional", "count": 102, "category": "modifier" },
        { "name": "Schema.Struct", "count": 91, "category": "composite" },
        { "name": "Schema.Number", "count": 81, "category": "primitive" },
        { "name": "Schema.Schema", "count": 60, "category": "type" },
        { "name": "Schema.TaggedError", "count": 38, "category": "error" },
        { "name": "Schema.Literal", "count": 29, "category": "literal" },
        { "name": "Schema.annotations", "count": 29, "category": "metadata" },
        { "name": "Schema.Array", "count": 19, "category": "composite" },
        { "name": "Schema.fromBrand", "count": 15, "category": "brand" },
        { "name": "Schema.asserts", "count": 10, "category": "validation" },
        { "name": "Schema.Unknown", "count": 10, "category": "primitive" },
        { "name": "Schema.int", "count": 8, "category": "refinement" },
        { "name": "Schema.Class", "count": 7, "category": "class" },
        { "name": "Schema.DateTimeUtc", "count": 6, "category": "temporal" },
        { "name": "Schema.Boolean", "count": 5, "category": "primitive" },
        { "name": "Schema.maxItems", "count": 4, "category": "refinement" },
        { "name": "Schema.enum", "count": 4, "category": "enum" },
        { "name": "Schema.Record", "count": 3, "category": "composite" },
        { "name": "Schema.minLength", "count": 3, "category": "refinement" },
        { "name": "Schema.NumberFromString", "count": 2, "category": "transform" },
        { "name": "Schema.nullable", "count": 2, "category": "modifier" },
        { "name": "Schema.positive", "count": 2, "category": "refinement" },
        { "name": "Schema.maxLength", "count": 2, "category": "refinement" },
        { "name": "Schema.minItems", "count": 2, "category": "refinement" },
        { "name": "Schema.standardSchemaV1", "count": 2, "category": "standard" },
        { "name": "Schema.BooleanFromString", "count": 1, "category": "transform" },
        { "name": "Schema.UUID", "count": 1, "category": "format" },
        { "name": "Schema.ULID", "count": 1, "category": "format" },
        { "name": "Schema.withDefault", "count": 1, "category": "modifier" },
        { "name": "Schema.transform", "count": 1, "category": "transform" }
      ]
    },
    "layer": {
      "totalCalls": 59,
      "uniqueAPIs": 8,
      "apis": [
        { "name": "Layer.provide", "count": 25, "category": "composition" },
        { "name": "Layer.make", "count": 18, "category": "construction" },
        { "name": "Layer.succeed", "count": 8, "category": "construction" },
        { "name": "Layer.effect", "count": 4, "category": "construction" },
        { "name": "Layer.empty", "count": 1, "category": "construction" },
        { "name": "Layer.provideMerge", "count": 1, "category": "composition" },
        { "name": "Layer.merge", "count": 1, "category": "composition" },
        { "name": "Layer.tap", "count": 1, "category": "inspection" }
      ]
    },
    "ref": {
      "totalCalls": 45,
      "uniqueAPIs": 5,
      "apis": [
        { "name": "Ref.update", "count": 20, "category": "mutation" },
        { "name": "Ref.get", "count": 17, "category": "read" },
        { "name": "Ref.make", "count": 6, "category": "construction" },
        { "name": "Ref.updateAndGet", "count": 1, "category": "mutation" },
        { "name": "Ref.set", "count": 1, "category": "mutation" }
      ]
    },
    "queue": {
      "totalCalls": 21,
      "uniqueAPIs": 2,
      "apis": [
        { "name": "Queue.offer", "count": 20, "category": "operation" },
        { "name": "Queue.unbounded", "count": 1, "category": "construction" }
      ]
    },
    "pubsub": {
      "totalCalls": 3,
      "uniqueAPIs": 3,
      "apis": [
        { "name": "PubSub.sliding", "count": 1, "category": "construction" },
        { "name": "PubSub.publish", "count": 1, "category": "operation" },
        { "name": "PubSub.subscribe", "count": 1, "category": "operation" }
      ]
    },
    "latch": {
      "totalCalls": 4,
      "uniqueAPIs": 3,
      "apis": [
        { "name": "Latch.open", "count": 2, "category": "operation" },
        { "name": "Latch.await", "count": 1, "category": "operation" },
        { "name": "Latch.make", "count": 1, "category": "construction" }
      ]
    },
    "option": {
      "totalCalls": 15,
      "uniqueAPIs": 3,
      "apis": [
        { "name": "Option.isNone", "count": 8, "category": "guard" },
        { "name": "Option.isSome", "count": 6, "category": "guard" },
        { "name": "Option.getOrElse", "count": 1, "category": "extraction" }
      ]
    },
    "config": {
      "totalCalls": 22,
      "uniqueAPIs": 5,
      "apis": [
        { "name": "Config.bucketName", "count": 9, "category": "custom" },
        { "name": "Config.region", "count": 5, "category": "custom" },
        { "name": "Config.string", "count": 4, "category": "primitive" },
        { "name": "Config.redacted", "count": 3, "category": "secure" },
        { "name": "Config.boolean", "count": 1, "category": "primitive" }
      ]
    },
    "logger": {
      "totalCalls": 6,
      "uniqueAPIs": 3,
      "apis": [
        { "name": "Logger.withMinimumLogLevel", "count": 2, "category": "configuration" },
        { "name": "Logger.pretty", "count": 2, "category": "formatter" },
        { "name": "LogLevel.Info", "count": 2, "category": "level" }
      ]
    },
    "httpApi": {
      "totalCalls": 66,
      "uniqueAPIs": 11,
      "apis": [
        { "name": "HttpApiSchema.annotations", "count": 29, "category": "metadata" },
        { "name": "HttpApiEndpoint.post", "count": 12, "category": "endpoint" },
        { "name": "HttpApiGroup.make", "count": 7, "category": "group" },
        { "name": "HttpApiBuilder.group", "count": 7, "category": "builder" },
        { "name": "HttpApiEndpoint.get", "count": 4, "category": "endpoint" },
        { "name": "HttpServerResponse.text", "count": 2, "category": "response" },
        { "name": "HttpApiEndpoint.put", "count": 1, "category": "endpoint" },
        { "name": "HttpApiBuilder.serve", "count": 1, "category": "builder" },
        { "name": "HttpApiBuilder.api", "count": 1, "category": "builder" },
        { "name": "HttpServer.withLogAddress", "count": 1, "category": "server" },
        { "name": "HttpServerResponse.stream", "count": 1, "category": "response" }
      ]
    },
    "hashmap": {
      "totalCalls": 51,
      "uniqueAPIs": 4,
      "apis": [
        { "name": "HashMap.empty", "count": 9, "category": "construction" },
        { "name": "HashMap.set", "count": 14, "category": "operation" },
        { "name": "HashMap.get", "count": 18, "category": "operation" },
        { "name": "HashMap.remove", "count": 10, "category": "operation" }
      ]
    },
    "other": {
      "totalCalls": 29,
      "uniqueAPIs": 12,
      "apis": [
        { "name": "Brand.nominal", "count": 9, "category": "branding" },
        { "name": "DateTime.unsafeNow", "count": 3, "category": "temporal" },
        { "name": "Redacted.make", "count": 3, "category": "security" },
        { "name": "Redacted.value", "count": 2, "category": "security" },
        { "name": "Exit.void", "count": 2, "category": "exit" },
        { "name": "Scope.close", "count": 2, "category": "resource" },
        { "name": "CloseableScope", "count": 2, "category": "resource" },
        { "name": "Fiber.value", "count": 2, "category": "concurrency" },
        { "name": "Duration.millis", "count": 1, "category": "temporal" },
        { "name": "Schedule.spaced", "count": 1, "category": "scheduling" },
        { "name": "Scope.make", "count": 1, "category": "resource" },
        { "name": "Fiber.get", "count": 1, "category": "concurrency" }
      ]
    }
  },
  "patterns": {
    "serviceDefinition": "Effect.Service pattern used in all domain services",
    "errorHandling": "Schema.TaggedError with HTTP annotations",
    "resourceManagement": "Effect.addFinalizer for cleanup",
    "dependencyInjection": "Layer-based DI throughout",
    "concurrency": "Ref + HashMap for concurrent state"
  }
}