Config.port and Config.branded functions have been added (#4892)

Co-authored-by: Tim <hello@timsmart.co>

Author: 2 people

.changeset/tasty-moose-move.md

@@ -0,0 +1,32 @@
+---
+"effect": minor
+---
+
+The `Config.port` and `Config.branded` functions have been added.
+
+```ts
+import { Brand, Config } from "effect"
+
+type DbPort = Brand.Branded<number, "DbPort">
+const DbPort = Brand.nominal<DbPort>()
+
+const dbPort: Config.Config<DbPort> = Config.branded(
+  Config.port("DB_PORT"),
+  DbPort
+)
+```
+
+```ts
+import { Brand, Config } from "effect"
+
+type Port = Brand.Branded<number, "Port">
+const Port = Brand.refined<Port>(
+  (num) =>
+    !Number.isNaN(num) && Number.isInteger(num) && num >= 1 && num <= 65535,
+  (n) => Brand.error(`Expected ${n} to be an TCP port`)
+)
+
+const dbPort: Config.Config<Port> = Config.number("DB_PORT").pipe(
+  Config.branded(Port)
+)
+```

packages/effect/dtslint/Config.tst.ts

@@ -1,12 +1,23 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-import { Config, hole, pipe } from "effect"
+import { Brand, Config, hole, pipe } from "effect"
 import { describe, expect, it } from "tstyche"
 
 declare const string: Config.Config<string>
 declare const number: Config.Config<number>
 declare const array: Array<Config.Config<string>>
 declare const record: Record<string, Config.Config<number>>
 
+type Int = Brand.Branded<number, "Int">
+const Int = Brand.refined<Int>(
+  (n) => Number.isInteger(n),
+  (n) => Brand.error(`Expected ${n} to be an integer`)
+)
+
+type Str = Brand.Branded<string, "Str">
+const Str = Brand.refined<Str>(
+  (n) => n.length > 2,
+  (n) => Brand.error(`Expected "${n}" to be longer than 2`)
+)
+
 describe("Config", () => {
   describe("all", () => {
     it("tuple", () => {
@@ -30,10 +41,24 @@ describe("Config", () => {
     })
   })
 
+  it("branded", () => {
+    // @ts-expect-error
+    Config.branded("NAME", Int)
+    // @ts-expect-error
+    Config.branded(number, Str)
+    // @ts-expect-error
+    number.pipe(Config.branded(Str))
+
+    expect(Config.branded(number, Int)).type.toBe<Config.Config<Int>>()
+    expect(Config.branded("NAME", Str)).type.toBe<Config.Config<Str>>()
+    expect(number.pipe(Config.branded(Int))).type.toBe<Config.Config<Int>>()
+    expect(pipe([string, number] as const, Config.all)).type.toBe<Config.Config<[string, number]>>()
+  })
+
   it("Config.Success helper type", () => {
     expect(hole<Config.Config.Success<typeof string>>()).type.toBe<string>()
     expect(hole<Config.Config.Success<typeof number>>()).type.toBe<number>()
-    const config = Config.all({ a: string, b: number })
-    expect(hole<Config.Config.Success<typeof config>>()).type.toBe<{ a: string; b: number }>()
+    const _config = Config.all({ a: string, b: number })
+    expect(hole<Config.Config.Success<typeof _config>>()).type.toBe<{ a: string; b: number }>()
   })
 })

packages/effect/src/Config.ts

@@ -1,6 +1,7 @@
 /**
  * @since 2.0.0
  */
+import type * as Brand from "./Brand.js"
 import type * as Chunk from "./Chunk.js"
 import type * as ConfigError from "./ConfigError.js"
 import type * as Duration from "./Duration.js"
@@ -129,7 +130,15 @@ export const array: <A>(config: Config<A>, name?: string) => Config<Array<A>> =
 export const boolean: (name?: string) => Config<boolean> = internal.boolean
 
 /**
- * Constructs a config for a URL value.
+ * Constructs a config for a network port [1, 65535].
+ *
+ * @since 3.16.0
+ * @category constructors
+ */
+export const port: (name?: string) => Config<number> = internal.port
+
+/**
+ * Constructs a config for an URL value.
  *
  * @since 3.11.0
  * @category constructors
@@ -360,6 +369,26 @@ export const redacted: {
   <A>(config: Config<A>): Config<Redacted.Redacted<A>>
 } = internal.redacted
 
+/**
+ * Constructs a config for a branded value.
+ *
+ * @since 3.16.0
+ * @category constructors
+ */
+export const branded: {
+  <A, B extends Brand.Branded<A, any>>(
+    constructor: Brand.Brand.Constructor<B>
+  ): (config: Config<A>) => Config<B>
+  <B extends Brand.Branded<string, any>>(
+    name: string | undefined,
+    constructor: Brand.Brand.Constructor<B>
+  ): Config<B>
+  <A, B extends Brand.Branded<A, any>>(
+    config: Config<A>,
+    constructor: Brand.Brand.Constructor<B>
+  ): Config<B>
+} = internal.branded
+
 /**
  * Constructs a config for a sequence of values.
  *

packages/effect/src/internal/config.ts

@@ -1,3 +1,4 @@
+import type * as Brand from "../Brand.js"
 import * as Chunk from "../Chunk.js"
 import type * as Config from "../Config.js"
 import * as ConfigError from "../ConfigError.js"
@@ -192,6 +193,33 @@ export const url = (name?: string): Config.Config<URL> => {
   return name === undefined ? config : nested(config, name)
 }
 
+/** @internal */
+export const port = (name?: string): Config.Config<number> => {
+  const config = primitive(
+    "a network port property",
+    (text) => {
+      const result = Number(text)
+
+      if (
+        Number.isNaN(result) ||
+        result.toString() !== text.toString() ||
+        !Number.isInteger(result) ||
+        result < 1 ||
+        result > 65535
+      ) {
+        return Either.left(
+          configError.InvalidData(
+            [],
+            `Expected a network port value but received ${text}`
+          )
+        )
+      }
+      return Either.right(result)
+    }
+  )
+  return name === undefined ? config : nested(config, name)
+}
+
 /** @internal */
 export const array = <A>(config: Config.Config<A>, name?: string): Config.Config<Array<A>> => {
   return pipe(chunk(config, name), map(Chunk.toArray))
@@ -444,6 +472,33 @@ export const redacted = <A>(
   return map(config, redacted_.make)
 }
 
+/** @internal */
+export const branded: {
+  <A, B extends Brand.Branded<A, any>>(
+    constructor: Brand.Brand.Constructor<B>
+  ): (config: Config.Config<A>) => Config.Config<B>
+  <B extends Brand.Branded<string, any>>(
+    name: string | undefined,
+    constructor: Brand.Brand.Constructor<B>
+  ): Config.Config<B>
+  <A, B extends Brand.Branded<A, any>>(
+    config: Config.Config<A>,
+    constructor: Brand.Brand.Constructor<B>
+  ): Config.Config<B>
+} = dual(2, <A, B extends Brand.Brand.Constructor<any>>(
+  nameOrConfig: Config.Config<NoInfer<A>> | string | undefined,
+  constructor: B
+) => {
+  const config: Config.Config<string | A> = isConfig(nameOrConfig) ? nameOrConfig : string(nameOrConfig)
+
+  return mapOrFail(config, (a) =>
+    constructor.either(a).pipe(
+      Either.mapLeft((brandErrors) =>
+        configError.InvalidData([], brandErrors.map((brandError) => brandError.message).join("\n"))
+      )
+    ))
+})
+
 /** @internal */
 export const hashSet = <A>(config: Config.Config<A>, name?: string): Config.Config<HashSet.HashSet<A>> => {
   const newConfig = map(chunk(config), HashSet.fromIterable)

packages/effect/test/Config.test.ts

@@ -1,6 +1,7 @@
 import { describe, it } from "@effect/vitest"
 import { assertFailure, assertSuccess, assertTrue, deepStrictEqual, strictEqual } from "@effect/vitest/utils"
 import {
+  Brand,
   Cause,
   Chunk,
   Config,
@@ -17,6 +18,12 @@ import {
   Secret
 } from "effect"
 
+type Str = Brand.Branded<string, "Str">
+const Str = Brand.refined<Str>(
+  (n) => n.length > 2,
+  (n) => Brand.error(`Brand: Expected ${n} to be longer than 2`)
+)
+
 const assertConfigError = <A>(
   config: Config.Config<A>,
   map: ReadonlyArray<readonly [string, string]>,
@@ -90,6 +97,69 @@ describe("Config", () => {
     })
   })
 
+  describe("port", () => {
+    it("name != undefined", () => {
+      const config = Config.port("WEBSITE_PORT")
+
+      assertConfig(
+        config,
+        [["WEBSITE_PORT", "123"]],
+        123
+      )
+      assertConfigError(
+        config,
+        [["WEBSITE_PORT", "abra-kadabra"]],
+        ConfigError.InvalidData(["WEBSITE_PORT"], "Expected a network port value but received abra-kadabra")
+      )
+      assertConfigError(
+        config,
+        [],
+        ConfigError.MissingData(["WEBSITE_PORT"], "Expected WEBSITE_PORT to exist in the provided map")
+      )
+    })
+  })
+
+  describe("branded", () => {
+    it("name != undefined", () => {
+      const config = Config.branded(Config.string("STR"), Str)
+
+      assertConfig(
+        config,
+        [["STR", "123"]],
+        Str("123")
+      )
+      assertConfigError(
+        config,
+        [["STR", "1"]],
+        ConfigError.InvalidData(["STR"], "Brand: Expected 1 to be longer than 2")
+      )
+      assertConfigError(
+        config,
+        [],
+        ConfigError.MissingData(["STR"], "Expected STR to exist in the provided map")
+      )
+    })
+    it("name != undefined from name", () => {
+      const config = Config.branded("STR", Str)
+
+      assertConfig(
+        config,
+        [["STR", "123"]],
+        Str("123")
+      )
+      assertConfigError(
+        config,
+        [["STR", "1"]],
+        ConfigError.InvalidData(["STR"], "Brand: Expected 1 to be longer than 2")
+      )
+      assertConfigError(
+        config,
+        [],
+        ConfigError.MissingData(["STR"], "Expected STR to exist in the provided map")
+      )
+    })
+  })
+
   describe("nonEmptyString", () => {
     it("name = undefined", () => {
       const config = Config.array(Config.nonEmptyString(), "ITEMS")