@effect/platform 0.72.2 → 0.73.1

package/README.md

@@ -5,6 +5,111 @@ Welcome to the documentation for `@effect/platform`, a library designed for crea
 > [!WARNING]
 > This documentation focuses on **unstable modules**. For stable modules, refer to the [official website documentation](https://effect.website/docs/guides/platform/introduction).
 
+# Running Your Main Program with runMain
+
+`runMain` helps you execute a main effect with built-in error handling, logging, and signal management. You can concentrate on your effect while `runMain` looks after finalizing resources, logging errors, and setting exit codes.
+
+- **Exit Codes**
+  If your effect fails or is interrupted, `runMain` assigns a suitable exit code (for example, `1` for errors and `0` for success).
+- **Logs**
+  By default, it records errors. This can be turned off if needed.
+- **Pretty Logging**
+  By default, error messages are recorded using a "pretty" format. You can switch this off when required.
+- **Interrupt Handling**
+  If the application receives `SIGINT` (Ctrl+C) or a similar signal, `runMain` will interrupt the effect and still run any necessary teardown steps.
+- **Teardown Logic**
+  You can rely on the default teardown or define your own. The default sets an exit code of `1` for a non-interrupted failure.
+
+## Usage Options
+
+When calling `runMain`, pass in a configuration object with these fields (all optional):
+
+- `disableErrorReporting`: If `true`, errors are not automatically logged.
+- `disablePrettyLogger`: If `true`, it avoids adding the "pretty" logger.
+- `teardown`: Provide a custom function for finalizing the program. If missing, the default sets exit code `1` for a non-interrupted failure.
+
+**Example** (Running a Successful Program)
+
+```ts
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect } from "effect"
+
+const success = Effect.succeed("Hello, World!")
+
+NodeRuntime.runMain(success)
+// No Output
+```
+
+**Example** (Running a Failing Program)
+
+```ts
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect } from "effect"
+
+const failure = Effect.fail("Uh oh!")
+
+NodeRuntime.runMain(failure)
+/*
+Output:
+[12:43:07.186] ERROR (#0):
+  Error: Uh oh!
+*/
+```
+
+**Example** (Running a Failing Program Without Pretty Logger)
+
+```ts
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect } from "effect"
+
+const failure = Effect.fail("Uh oh!")
+
+NodeRuntime.runMain(failure, { disablePrettyLogger: true })
+/*
+Output:
+timestamp=2025-01-14T11:43:46.276Z level=ERROR fiber=#0 cause="Error: Uh oh!"
+*/
+```
+
+**Example** (Running a Failing Program Without Error Reporting)
+
+```ts
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect } from "effect"
+
+const failure = Effect.fail("Uh oh!")
+
+NodeRuntime.runMain(failure, { disableErrorReporting: true })
+// No Output
+```
+
+**Example** (Running a Failing Program With Custom Teardown)
+
+```ts
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect } from "effect"
+
+const failure = Effect.fail("Uh oh!")
+
+NodeRuntime.runMain(failure, {
+  teardown: function customTeardown(exit, onExit) {
+    if (exit._tag === "Failure") {
+      console.error("Program ended with an error.")
+      onExit(1)
+    } else {
+      console.log("Program finished successfully.")
+      onExit(0)
+    }
+  }
+})
+/*
+Output:
+[12:46:39.871] ERROR (#0):
+  Error: Uh oh!
+Program ended with an error.
+*/
+```
+
 # HTTP API
 
 ## Overview
@@ -4310,3 +4415,535 @@ const handler = HttpApp.toWebHandler(router)
 const response = await handler(new Request("http://localhost:3000/foo"))
 console.log(await response.text()) // Output: content 2
 ```
+
+# Url
+
+The `Url` module provides utilities for constructing and working with `URL` objects in a functional style. It includes:
+
+- A safe constructor for parsing URLs from strings.
+- Functions for immutably updating `URL` properties like `host`, `href`, and `search`.
+- Tools for reading and modifying URL parameters using the `UrlParams` module.
+- A focus on immutability, creating new `URL` instances for every change.
+
+## Creating a URL
+
+### fromString
+
+This function takes a string and attempts to parse it into a `URL` object. If the string is invalid, it returns an `Either.Left` containing an `IllegalArgumentException` with the error details. Otherwise, it returns an `Either.Right` containing the parsed `URL`.
+
+You can optionally provide a `base` parameter to resolve relative URLs. When supplied, the function treats the input `url` as relative to the `base`.
+
+**Example** (Parsing a URL with Optional Base)
+
+```ts
+import { Url } from "@effect/platform"
+import { Either } from "effect"
+
+// Parse an absolute URL
+//
+//      ┌─── Either<URL, IllegalArgumentException>
+//      ▼
+const parsed = Url.fromString("https://example.com/path")
+
+if (Either.isRight(parsed)) {
+  console.log("Parsed URL:", parsed.right.toString())
+} else {
+  console.log("Error:", parsed.left.message)
+}
+// Output: Parsed URL: https://example.com/path
+
+// Parse a relative URL with a base
+const relativeParsed = Url.fromString("/relative-path", "https://example.com")
+
+if (Either.isRight(relativeParsed)) {
+  console.log("Parsed relative URL:", relativeParsed.right.toString())
+} else {
+  console.log("Error:", relativeParsed.left.message)
+}
+// Output: Parsed relative URL: https://example.com/relative-path
+```
+
+## Immutably Changing URL Properties
+
+The `Url` module offers a set of functions for updating properties of a `URL` object without modifying the original instance. These functions create and return a new `URL` with the specified updates, preserving the immutability of the original.
+
+### Available Setters
+
+| Setter        | Description                                               |
+| ------------- | --------------------------------------------------------- |
+| `setHash`     | Updates the hash fragment of the URL.                     |
+| `setHost`     | Updates the host (domain and port) of the URL.            |
+| `setHostname` | Updates the domain of the URL without modifying the port. |
+| `setHref`     | Replaces the entire URL string.                           |
+| `setPassword` | Updates the password used for authentication.             |
+| `setPathname` | Updates the path of the URL.                              |
+| `setPort`     | Updates the port of the URL.                              |
+| `setProtocol` | Updates the protocol (e.g., `http`, `https`).             |
+| `setSearch`   | Updates the query string of the URL.                      |
+| `setUsername` | Updates the username used for authentication.             |
+
+**Example** (Using Setters to Modify URL Properties)
+
+```ts
+import { Url } from "@effect/platform"
+import { pipe } from "effect"
+
+const myUrl = new URL("https://example.com")
+
+// Changing protocol, host, and port
+const newUrl = pipe(
+  myUrl,
+  Url.setProtocol("http:"),
+  Url.setHost("google.com"),
+  Url.setPort("8080")
+)
+
+console.log("Original:", myUrl.toString())
+// Output: Original: https://example.com/
+
+console.log("New:", newUrl.toString())
+// Output: New: http://google.com:8080/
+```
+
+### mutate
+
+For more advanced modifications, use the `mutate` function. It clones the original `URL` object and applies a callback to the clone, allowing multiple updates at once.
+
+**Example** (Applying Multiple Changes with `mutate`)
+
+```ts
+import { Url } from "@effect/platform"
+
+const myUrl = new URL("https://example.com")
+
+const mutatedUrl = Url.mutate(myUrl, (url) => {
+  url.username = "user"
+  url.password = "pass"
+})
+
+console.log("Mutated:", mutatedUrl.toString())
+// Output: Mutated: https://user:pass@example.com/
+```
+
+## Reading and Writing URL Parameters
+
+The `Url` module provides utilities for working with URL query parameters. These utilities allow you to read existing parameters and write new ones, all while maintaining immutability. This functionality is supported by the `UrlParams` module.
+
+You can extract the query parameters from a `URL` object using the `urlParams` function.
+
+To modify or add query parameters, use the `setUrlParams` function. This function creates a new `URL` with the updated query string.
+
+**Example** (Reading and Writing Parameters)
+
+```ts
+import { Url, UrlParams } from "@effect/platform"
+
+const myUrl = new URL("https://example.com?foo=bar")
+
+// Read parameters
+const params = Url.urlParams(myUrl)
+
+console.log(params)
+// Output: [ [ 'foo', 'bar' ] ]
+
+// Write parameters
+const updatedUrl = Url.setUrlParams(
+  myUrl,
+  UrlParams.fromInput([["key", "value"]])
+)
+
+console.log(updatedUrl.toString())
+// Output: https://example.com/?key=value
+```
+
+### Modifying URL Parameters
+
+The `modifyUrlParams` function allows you to read, modify, and overwrite URL parameters in a single operation.
+
+**Example** (Appending a Parameter to a URL)
+
+```ts
+import { Url, UrlParams } from "@effect/platform"
+
+const myUrl = new URL("https://example.com?foo=bar")
+
+const changedUrl = Url.modifyUrlParams(myUrl, UrlParams.append("key", "value"))
+
+console.log(changedUrl.toString())
+// Output: https://example.com/?foo=bar&key=value
+```
+
+# OpenApiJsonSchema
+
+The `OpenApiJsonSchema` module provides utilities to transform `Schema` objects into JSON schemas that comply with the OpenAPI Specification. These utilities are especially helpful for generating OpenAPI documentation or working with tools that require OpenAPI-compliant schemas.
+
+## Creating a JSON Schema from a Schema
+
+This module enables you to convert `Schema` objects into OpenAPI-compatible JSON schemas, making it easy to integrate with tools like Swagger or other OpenAPI-based frameworks.
+
+**Example** (Generating a JSON Schema from a String Schema)
+
+```ts
+import { OpenApiJsonSchema } from "@effect/platform"
+import { Schema } from "effect"
+
+const schema = Schema.String
+
+// Convert the schema to OpenAPI JSON Schema
+const openApiSchema = OpenApiJsonSchema.make(schema)
+
+console.log(JSON.stringify(openApiSchema, null, 2))
+/*
+Output:
+{
+  "type": "string"
+}
+*/
+```
+
+## Differences from JSONSchema
+
+The `OpenApiJsonSchema` module differs from the `JSONSchema` module in several ways. These differences are tailored to align with the OpenAPI Specification.
+
+### `$schema` Property Omission
+
+OpenAPI schemas do not include the `$schema` property, while JSON schemas do.
+
+**Example** (Comparison of `$schema` Property)
+
+```ts
+import { OpenApiJsonSchema } from "@effect/platform"
+import { JSONSchema, Schema } from "effect"
+
+const schema = Schema.String
+
+const openApiSchema = OpenApiJsonSchema.make(schema)
+const jsonSchema = JSONSchema.make(schema)
+
+console.log(JSON.stringify(openApiSchema, null, 2))
+/*
+Output:
+{
+  "type": "string"
+}
+*/
+
+console.log(JSON.stringify(jsonSchema, null, 2))
+/*
+Output:
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string"
+}
+*/
+```
+
+### Handling of `null` Values
+
+OpenAPI does not support `{ "type": "null" }`. Instead, it uses an `enum` containing `null` to represent nullable values.
+
+**Example** (Representation of `null` Values)
+
+```ts
+import { OpenApiJsonSchema } from "@effect/platform"
+import { JSONSchema, Schema } from "effect"
+
+const schema = Schema.Null
+
+const openApiSchema = OpenApiJsonSchema.make(schema)
+const jsonSchema = JSONSchema.make(schema)
+
+console.log(JSON.stringify(openApiSchema, null, 2))
+/*
+Output:
+{
+  "enum": [
+    null
+  ]
+}
+*/
+
+console.log(JSON.stringify(jsonSchema, null, 2))
+/*
+Output:
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "null"
+}
+*/
+```
+
+### Nullable Values
+
+OpenAPI uses the `nullable` property to indicate that a value can be `null`, whereas JSON schemas use an `anyOf` structure.
+
+**Example** (Nullable Property Representation)
+
+```ts
+import { OpenApiJsonSchema } from "@effect/platform"
+import { JSONSchema, Schema } from "effect"
+
+const schema = Schema.NullOr(Schema.String)
+
+const openApiSchema = OpenApiJsonSchema.make(schema)
+const jsonSchema = JSONSchema.make(schema)
+
+console.log(JSON.stringify(openApiSchema, null, 2))
+/*
+Output:
+{
+  "type": "string",
+  "nullable": true
+}
+*/
+
+console.log(JSON.stringify(jsonSchema, null, 2))
+/*
+Output:
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
+*/
+```
+
+### `contentSchema` Support
+
+OpenAPI schemas include a `contentSchema` property, which allows you to describe the structure of the content for a media type (e.g., `application/json`). This feature is not available in JSON schemas (Draft 7), making `contentSchema` particularly useful for defining structured payloads in OpenAPI documentation.
+
+**Note**: Use `contentSchema` to define the internal structure of media types like `application/json` in OpenAPI specifications. This property provides clarity and detail for tools and users interacting with the API, especially when handling structured payloads.
+
+**Example** (Defining a Schema with `contentSchema` for JSON Content)
+
+```ts
+import { OpenApiJsonSchema } from "@effect/platform"
+import { JSONSchema, Schema } from "effect"
+
+// Define a schema for parsing JSON content
+const schema = Schema.parseJson(Schema.Struct({ a: Schema.String }))
+
+const openApiSchema = OpenApiJsonSchema.make(schema)
+const jsonSchema = JSONSchema.make(schema)
+
+console.log(JSON.stringify(openApiSchema, null, 2))
+/*
+Output:
+{
+  "type": "string",
+  "contentMediaType": "application/json",
+  "contentSchema": {
+    "type": "object",
+    "required": [
+      "a"
+    ],
+    "properties": {
+      "a": {
+        "type": "string"
+      }
+    },
+    "additionalProperties": false
+  }
+}
+*/
+
+console.log(JSON.stringify(jsonSchema, null, 2))
+/*
+Output:
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "a"
+  ],
+  "properties": {
+    "a": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}
+*/
+```
+
+### makeWithDefs
+
+The `makeWithDefs` function generates OpenAPI-compatible JSON schemas and collects schema definitions in a shared object. This is especially useful for consolidating multiple schemas into a single OpenAPI specification, enabling schema reuse across your API.
+
+**Example** (Generating OpenAPI Schema with Definitions)
+
+```ts
+import { OpenApiJsonSchema } from "@effect/platform"
+import { Schema } from "effect"
+
+// Define a schema with an identifier annotation
+const schema = Schema.Struct({ a: Schema.String }).annotations({
+  identifier: "MyStruct"
+})
+
+// Create a definitions object
+const defs = {}
+
+// Generate the OpenAPI schema while collecting definitions
+const openApiSchema = OpenApiJsonSchema.makeWithDefs(schema, { defs })
+
+console.log(JSON.stringify(openApiSchema, null, 2))
+/*
+Output:
+{
+  "$ref": "#/components/schemas/MyStruct"
+}
+*/
+
+console.log(JSON.stringify(defs, null, 2))
+/*
+Output:
+{
+  "MyStruct": {
+    "type": "object",
+    "required": [
+      "a"
+    ],
+    "properties": {
+      "a": {
+        "type": "string"
+      }
+    },
+    "additionalProperties": false
+  }
+}
+*/
+```
+
+**Example** (Combining Multiple Schemas into One OpenAPI Specification)
+
+```ts
+import { OpenApiJsonSchema } from "@effect/platform"
+import { Schema } from "effect"
+
+// Define multiple schemas with unique identifiers
+const schema1 = Schema.Struct({ a: Schema.String }).annotations({
+  identifier: "MyStruct1"
+})
+const schema2 = Schema.Struct({ b: Schema.Number }).annotations({
+  identifier: "MyStruct2"
+})
+
+// Create a shared definitions object
+const defs = {}
+
+// Use `makeWithDefs` to generate schemas for API paths
+const paths = {
+  paths: {
+    "/path1": {
+      get: {
+        responses: {
+          "200": {
+            content: {
+              "application/json": {
+                schema: OpenApiJsonSchema.makeWithDefs(schema1, { defs })
+              }
+            }
+          }
+        }
+      }
+    },
+    "/path2": {
+      get: {
+        responses: {
+          "200": {
+            content: {
+              "application/json": {
+                schema: OpenApiJsonSchema.makeWithDefs(schema2, { defs })
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+// Combine paths and definitions into a single OpenAPI schema
+const openApiSchema = {
+  components: {
+    schemas: defs
+  },
+  paths
+}
+
+console.log(JSON.stringify(openApiSchema, null, 2))
+/*
+Output:
+{
+  "components": {
+    "schemas": {
+      "MyStruct1": {
+        "type": "object",
+        "required": [
+          "a"
+        ],
+        "properties": {
+          "a": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "MyStruct2": {
+        "type": "object",
+        "required": [
+          "b"
+        ],
+        "properties": {
+          "b": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "paths": {
+    "paths": {
+      "/path1": {
+        "get": {
+          "responses": {
+            "200": {
+              "content": {
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/MyStruct1"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/path2": {
+        "get": {
+          "responses": {
+            "200": {
+              "content": {
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/MyStruct2"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+*/
+```

package/Url/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/Url.js",
+  "module": "../dist/esm/Url.js",
+  "types": "../dist/dts/Url.d.ts",
+  "sideEffects": []
+}