effect 4.0.7 → 4.1.1

package/src/Equal.ts

@@ -398,8 +398,8 @@ export function makeCompareSet<A>(equivalence: Equivalence<A>) {
  * **Details**
  *
  * - Pure function, no side effects.
- * - Returns `true` if and only if `u` has a property keyed by
- *   {@link symbol}.
+ * - Returns `true` if and only if `u` has a function keyed by {@link symbol}.
+ *   Data that merely carries the key, such as parsed JSON, is not `Equal`.
  * - Acts as a TypeScript type guard, narrowing the input to {@link Equal}.
  *
  * **Example** (Checking Equal values)
@@ -428,7 +428,7 @@ export function makeCompareSet<A>(equivalence: Equivalence<A>) {
  * @category guards
  * @since 2.0.0
  */
-export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol)
+export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol) && typeof u[symbol] === "function"
 
 /**
  * Wraps {@link equals} as an `Equivalence<A>`.

package/src/FileSystem.ts

@@ -17,6 +17,7 @@ import * as Cause from "./Cause.ts"
 import * as Context from "./Context.ts"
 import * as Effect from "./Effect.ts"
 import { pipe } from "./Function.ts"
+import * as Glob from "./internal/glob.ts"
 import * as Layer from "./Layer.ts"
 import * as Option from "./Option.ts"
 import { badArgument, type PlatformError, systemError } from "./PlatformError.ts"
@@ -130,13 +131,36 @@ export interface FileSystem {
     gid: number
   ) => Effect.Effect<void, PlatformError>
   /**
-   * Glob a directory.
+   * Finds paths under `root` that match a glob pattern.
+   *
+   * **Details**
+   *
+   * Patterns follow `Glob.make`: wildcards skip names that start with `.`
+   * unless the pattern segment starts with `.` or `dot` is `true`, and
+   * `dir/**` includes `dir` itself. Results are `/`-separated paths relative
+   * to `root` (or absolute for an absolute pattern), visited depth-first with
+   * each directory's entries sorted by name. `**` does not traverse symbolic
+   * links to directories, but a link named by another segment is followed.
+   * Paths that match an `exclude` pattern are dropped, and excluded
+   * directories are not read. Entries whose type cannot be determined, such
+   * as broken links, are treated as files.
+   *
+   * Read failures at the root or a leading literal directory propagate. Missing
+   * paths return an empty result; unreadable wildcard-reached directories are
+   * skipped.
+   *
+   * **Gotchas**
+   *
+   * Wildcard matching is case-sensitive. Leading literal segments use `stat`,
+   * so their case sensitivity follows the file system and results retain the
+   * pattern's spelling.
    */
   readonly glob: (
     pattern: string,
     options?: {
       readonly root?: string | undefined
       readonly exclude?: ReadonlyArray<string> | undefined
+      readonly dot?: boolean | undefined
     }
   ) => Effect.Effect<Array<string>, PlatformError>
   /**
@@ -254,6 +278,22 @@ export interface FileSystem {
       readonly recursive?: boolean | undefined
     }
   ) => Effect.Effect<Array<string>, PlatformError>
+  /**
+   * Lists a directory with the type of each entry.
+   *
+   * **Details**
+   *
+   * Returns the same bare names as `readDirectory(path)`, excluding `.` and
+   * `..`, in no particular order. Types describe entries, not symlink targets.
+   * `"Unknown"` is allowed when the listing cannot determine the type, and
+   * `glob` then falls back to `stat`.
+   *
+   * **Gotchas**
+   *
+   * Wrappers that change `readDirectory`, such as by prefixing paths, must
+   * apply the same change here for `glob` to list the correct directory.
+   */
+  readonly readDirectoryEntries: (path: string) => Effect.Effect<ReadonlyArray<DirectoryEntry>, PlatformError>
   /**
    * Read the contents of a file.
    */
@@ -485,6 +525,21 @@ export type OpenFlag =
  */
 export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Service("effect/FileSystem")
 
+/**
+ * A directory entry with its type, independent of any symlink target.
+ * `"Unknown"` means the listing could not determine the type.
+ *
+ * @see {@link FileSystem} `readDirectoryEntries`, which returns these entries
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface DirectoryEntry {
+  readonly name: string
+  readonly type: File.Type
+}
+
 /**
  * Creates a FileSystem implementation from a partial implementation.
  *
@@ -497,8 +552,10 @@ export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Servi
  * **Details**
  *
  * This function takes a partial FileSystem implementation and automatically provides
- * default implementations for `exists`, `readFileString`, `stream`, `sink`, and
- * `writeFileString` methods based on the provided core methods.
+ * default implementations for `exists`, `glob`, `readFileString`, `stream`, `sink`,
+ * and `writeFileString` methods based on the provided core methods. `glob` walks
+ * the tree with `readDirectoryEntries`, using `stat` and `readLink` for entries
+ * whose type is `"Unknown"`.
  *
  * @see {@link makeNoop} for a testing stub that accepts method overrides without requiring a complete implementation
  * @see {@link layerNoop} for providing a no-op `FileSystem` as a `Layer` in tests
@@ -508,11 +565,12 @@ export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Servi
  * @since 4.0.0
  */
 export const make = (
-  impl: Omit<FileSystem, typeof TypeId | "exists" | "readFileString" | "stream" | "sink" | "writeFileString">
+  impl: Omit<FileSystem, typeof TypeId | "exists" | "glob" | "readFileString" | "stream" | "sink" | "writeFileString">
 ): FileSystem =>
   FileSystem.of({
     ...impl,
     [TypeId]: TypeId,
+    glob: Glob.make(impl),
     exists: (path) =>
       pipe(
         impl.access(path),
@@ -702,6 +760,9 @@ export const makeNoop = (fileSystem: Partial<FileSystem>): FileSystem =>
     readDirectory(path) {
       return Effect.fail(notFound("readDirectory", path))
     },
+    readDirectoryEntries(path) {
+      return Effect.fail(notFound("readDirectoryEntries", path))
+    },
     readFile(path) {
       return Effect.fail(notFound("readFile", path))
     },

package/src/Glob.ts

@@ -0,0 +1,205 @@
+/**
+ * Matches `/`-separated paths without accessing the file system, using the
+ * same pattern syntax as `FileSystem.glob`.
+ *
+ * @stability experimental
+ * @since 4.0.0
+ */
+import { format } from "./Formatter.ts"
+import { dual } from "./Function.ts"
+import { type Inspectable, NodeInspectSymbol } from "./Inspectable.ts"
+import * as internal from "./internal/glob.ts"
+import { type Pipeable, pipeArguments } from "./Pipeable.ts"
+
+const TypeId = "~effect/Glob"
+
+/**
+ * A compiled glob pattern.
+ *
+ * **Details**
+ *
+ * `pattern` is the source text and `dot` records whether wildcards match names
+ * that start with `.`. Match paths against it with {@link match}.
+ *
+ * @see {@link make} for compiling a pattern
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export interface Glob extends Pipeable, Inspectable {
+  readonly [TypeId]: typeof TypeId
+  readonly pattern: string
+  readonly dot: boolean
+}
+
+interface GlobImpl extends Glob {
+  readonly compiled: internal.Compiled
+}
+
+const GlobProto = {
+  [TypeId]: TypeId,
+  toJSON(this: Glob) {
+    return { _id: "Glob", pattern: this.pattern, dot: this.dot }
+  },
+  toString(this: Glob) {
+    return `Glob(${format(this.toJSON())})`
+  },
+  [NodeInspectSymbol](this: Glob) {
+    return this.toJSON()
+  },
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+/**
+ * Compiles a glob pattern into a reusable `Glob`.
+ *
+ * **Details**
+ *
+ * Patterns use `/` as the separator. `*` matches any run of characters within
+ * one path segment, `?` matches one character, and `[...]` matches one
+ * character from a set, with `!` or `^` negating it and POSIX classes such as
+ * `[[:digit:]]` allowed. `{a,b}` expands to each alternative and may nest. A
+ * segment that is exactly `**` matches zero or more whole segments. A trailing
+ * `/` matches only directories, and `\` makes the next character literal.
+ *
+ * **Gotchas**
+ *
+ * Wildcards and `**` skip names that start with `.` unless the pattern segment
+ * itself starts with `.` or `dot` is `true`; they never match `.` or `..`.
+ * `x/.` is the same as `x/`, and a `.` or `..` segment after `**` makes the
+ * pattern match nothing, as does the empty pattern. UNC patterns and paths
+ * such as `//server/share` are not supported and never match. Braces and
+ * commas inside `[...]` are class members. Extended glob syntax and leading
+ * `!` negation are not interpreted, but ordinary wildcards still apply within
+ * them (for example, `?(a)` matches `x(a)`). Malformed syntax, such as an
+ * unclosed `[`, matches literally. Braces also stay literal if expansion would
+ * exceed 10,000 alternatives.
+ *
+ * **Example** (Matching source files)
+ *
+ * ```ts import.meta.vitest
+ * import { Glob } from "effect"
+ *
+ * const sources = Glob.make("src/**\/*.{ts,tsx}")
+ *
+ * Glob.match(sources, "src/index.ts") // => true
+ * Glob.match(sources, "src/ui/Button.tsx") // => true
+ * Glob.match(sources, "src/.cache/index.ts") // => false
+ * Glob.match(sources, "test/index.ts") // => false
+ * ```
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (pattern: string, options?: {
+  /** Whether wildcards and `**` match names that start with `.`. */
+  readonly dot?: boolean | undefined
+}): Glob => {
+  const dot = options?.dot ?? false
+  const self = Object.create(GlobProto)
+  self.pattern = pattern
+  self.dot = dot
+  self.compiled = internal.compile([pattern], dot)
+  return self
+}
+
+/**
+ * Tests whether a `/`-separated path matches a `Glob`.
+ *
+ * **Details**
+ *
+ * Empty segments and `./` segments in the path are ignored. A trailing `/`
+ * marks the path as a directory, which a pattern ending in `/` requires.
+ *
+ * **Example** (Filtering paths)
+ *
+ * ```ts import.meta.vitest
+ * import { Glob, pipe } from "effect"
+ *
+ * const tests = Glob.make("**\/*.test.ts")
+ * const paths = ["src/a.ts", "src/a.test.ts", "test/b.test.ts"]
+ *
+ * paths.filter((path) => Glob.match(tests, path)) // => ["src/a.test.ts", "test/b.test.ts"]
+ * pipe(tests, Glob.match("./src/a.test.ts")) // => true
+ * ```
+ *
+ * @stability experimental
+ * @category predicates
+ * @since 4.0.0
+ */
+export const match: {
+  /**
+   * Tests whether a `/`-separated path matches a `Glob`.
+   *
+   * **Details**
+   *
+   * Empty segments and `./` segments in the path are ignored. A trailing `/`
+   * marks the path as a directory, which a pattern ending in `/` requires.
+   *
+   * **Example** (Filtering paths)
+   *
+   * ```ts import.meta.vitest
+   * import { Glob, pipe } from "effect"
+   *
+   * const tests = Glob.make("**\/*.test.ts")
+   * const paths = ["src/a.ts", "src/a.test.ts", "test/b.test.ts"]
+   *
+   * paths.filter((path) => Glob.match(tests, path)) // => ["src/a.test.ts", "test/b.test.ts"]
+   * pipe(tests, Glob.match("./src/a.test.ts")) // => true
+   * ```
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (path: string): (self: Glob) => boolean
+  /**
+   * Tests whether a `/`-separated path matches a `Glob`.
+   *
+   * **Details**
+   *
+   * Empty segments and `./` segments in the path are ignored. A trailing `/`
+   * marks the path as a directory, which a pattern ending in `/` requires.
+   *
+   * **Example** (Filtering paths)
+   *
+   * ```ts import.meta.vitest
+   * import { Glob, pipe } from "effect"
+   *
+   * const tests = Glob.make("**\/*.test.ts")
+   * const paths = ["src/a.ts", "src/a.test.ts", "test/b.test.ts"]
+   *
+   * paths.filter((path) => Glob.match(tests, path)) // => ["src/a.test.ts", "test/b.test.ts"]
+   * pipe(tests, Glob.match("./src/a.test.ts")) // => true
+   * ```
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (self: Glob, path: string): boolean
+} = dual(2, (self: Glob, path: string): boolean => internal.match((self as GlobImpl).compiled, path))
+
+/**
+ * Escapes glob syntax so a string matches only itself.
+ *
+ * **Example** (Matching a literal file name)
+ *
+ * ```ts import.meta.vitest
+ * import { Glob } from "effect"
+ *
+ * const name = "report[1].txt"
+ *
+ * Glob.match(Glob.make(name), name) // => false
+ * Glob.match(Glob.make(Glob.escape(name)), name) // => true
+ * ```
+ *
+ * @stability experimental
+ * @category utils
+ * @since 4.0.0
+ */
+export const escape = (input: string): string => input.replace(/[\\*?[\]{}]/g, "\\$&")

package/src/Hash.ts

@@ -140,7 +140,7 @@ export const hash: <A>(self: A) => number = <A>(self: A) => {
         const seen = backEdges
         let h: number
         try {
-          if (symbol in self) {
+          if (isHash(self)) {
             h = (self as Hash)[symbol]()
           } else if (typeof self === "function") {
             h = random(self)
@@ -351,8 +351,9 @@ export const optimize = (n: number): number => (n & 0xbfffffff) | ((n >>> 1) & 0
  *
  * **Details**
  *
- * This function determines whether a given value has the Hash symbol property,
- * indicating that it can provide its own hash value implementation.
+ * This function determines whether a given value has a function under the Hash
+ * symbol, indicating that it can provide its own hash value implementation.
+ * Data that merely carries the key, such as parsed JSON, is hashed as data.
  *
  * **Example** (Checking for Hash support)
  *
@@ -374,7 +375,7 @@ export const optimize = (n: number): number => (n & 0xbfffffff) | ((n >>> 1) & 0
  * @category guards
  * @since 2.0.0
  */
-export const isHash = (u: unknown): u is Hash => hasProperty(u, symbol)
+export const isHash = (u: unknown): u is Hash => hasProperty(u, symbol) && typeof u[symbol] === "function"
 
 const float64 = new DataView(new ArrayBuffer(8))
 

package/src/Iterable.ts

@@ -1223,15 +1223,18 @@ export const takeWhile: {
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Iterable<A>
 } = dual(2, <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Iterable<A> => ({
   [Symbol.iterator]() {
-    const iterator = self[Symbol.iterator]()
+    let iterator: Iterator<A> | undefined = self[Symbol.iterator]()
     let i = 0
     return {
       next() {
-        const result = iterator.next()
-        if (result.done || !predicate(result.value, i++)) {
-          return { done: true, value: undefined }
+        if (iterator !== undefined) {
+          const result = iterator.next()
+          if (!result.done && predicate(result.value, i++)) {
+            return result
+          }
+          iterator = undefined
         }
-        return result
+        return { done: true, value: undefined }
       }
     }
   }

package/src/Match.ts

@@ -37,6 +37,31 @@ type ValueTagHandlers<I> = {
   readonly [Tag in Types.Tags<"_tag", I> & string]: (_: Extract<I, { readonly _tag: Tag }>) => any
 }
 
+// Members of `R` that a literal record can dispatch on: finite string / number
+// literals whose runtime key no other string / number member can produce.
+// Widened `string` / `number` and template literals add no keys, and a literal
+// is dropped when another member spells the same key (`1` with `"1"` or
+// `string`, `"1"` or `"NaN"` with `number`).
+type LiteralKeys<R, All = Extract<R, string | number>> = R extends string | number
+  ? {} extends Record<R, unknown> ? never
+  : R extends number ? `${R}` extends All ? never : R
+  : R extends `${infer N extends number}` ? N extends All ? never : R
+  : R extends "NaN" | "Infinity" | "-Infinity" ? number extends All ? never : R
+  : R
+  : never
+
+type LiteralHandlers<R, Ret> = [Exclude<R, LiteralKeys<R>>] extends [never] ? {
+    readonly [K in LiteralKeys<R>]: (_: K) => Ret
+  }
+  : never
+
+type PartialLiteralHandlers<R, Ret> = {
+  readonly [K in LiteralKeys<R>]?: ((_: K) => Ret) | undefined
+}
+
+// Only keys with a defined handler remove a literal from the remaining input.
+type HandledLiterals<P> = { readonly [K in keyof P]-?: undefined extends P[K] ? never : K }[keyof P]
+
 /**
  * Marker used by `Matcher` to distinguish matchers created with `Match.value`.
  *
@@ -1391,6 +1416,108 @@ export const tagsExhaustive: <
 ) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>> =
   internal.tagsExhaustive
 
+/**
+ * Matches string and number literal values, mapping each literal to a
+ * corresponding handler.
+ *
+ * **Details**
+ *
+ * Each handler receives the matched literal. Handled literals are removed from
+ * the remaining input, while unhandled literals and any other members (such as
+ * `null`, objects, or widened `string` / `number` types) are left for later
+ * cases. Keys must be finite string or number literals of the remaining input;
+ * unions containing both a number and its string spelling, such as
+ * `1 | "1"`, are rejected because both share the same runtime key.
+ *
+ * **Example** (Mapping literal handlers)
+ *
+ * ```ts import.meta.vitest
+ * import { Match } from "effect"
+ *
+ * type Status = "draft" | "review" | "published"
+ *
+ * const isEditable = Match.type<Status>().pipe(
+ *   Match.literals({ draft: () => true, review: () => true }),
+ *   Match.orElse(() => false)
+ * )
+ *
+ * isEditable("review") // => true
+ * isEditable("published") // => false
+ * ```
+ *
+ * @see {@link literalsExhaustive} for handling every literal and finalizing the matcher
+ *
+ * @stability unstable
+ * @category defining patterns
+ * @since 4.1.0
+ */
+export const literals: <
+  R,
+  Ret,
+  P extends
+    & PartialLiteralHandlers<R, Ret>
+    & { readonly [K in Exclude<keyof P, LiteralKeys<R>>]: never }
+>(
+  fields: Contextual<P, PartialLiteralHandlers<R, Ret>>
+) => <I, F, A, Pr>(
+  self: Matcher<I, F, R, A, Pr, Ret>
+) => Matcher<
+  I,
+  Types.AddWithout<F, Extract<R, HandledLiterals<P>>>,
+  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, HandledLiterals<P>>>>,
+  A | ReturnType<P[keyof P] & {}>,
+  Pr,
+  Ret
+> = internal.literals
+
+/**
+ * Matches string and number literal values and requires handling of all
+ * remaining cases.
+ *
+ * **Details**
+ *
+ * This is the exhaustive variant of {@link literals}. Every remaining member
+ * must be a finite string or number literal with a corresponding handler, so a
+ * missing literal, a widened `string` / `number` type, or any other unhandled
+ * member is reported by TypeScript.
+ *
+ * **Example** (Handling all literal cases)
+ *
+ * ```ts import.meta.vitest
+ * import { Match } from "effect"
+ *
+ * type Status = "draft" | "review" | "published"
+ *
+ * const label = Match.type<Status>().pipe(
+ *   Match.literalsExhaustive({
+ *     draft: () => "Draft",
+ *     review: () => "In review",
+ *     published: () => "Live"
+ *   })
+ * )
+ *
+ * label("review") // => "In review"
+ * ```
+ *
+ * @see {@link literals} for defining literal handlers without finalizing the matcher
+ *
+ * @stability unstable
+ * @category defining patterns
+ * @since 4.1.0
+ */
+export const literalsExhaustive: <
+  R,
+  Ret,
+  P extends
+    & LiteralHandlers<R, Ret>
+    & { readonly [K in Exclude<keyof P, LiteralKeys<R>>]: never }
+>(
+  fields: Contextual<P, LiteralHandlers<R, Ret>>
+) => <I, F, A, Pr>(
+  self: Matcher<I, F, R, A, Pr, Ret>
+) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>> =
+  internal.literalsExhaustive
+
 /**
  * Creates a pattern that excludes a specific value while allowing all others.
  *

package/src/Path.ts

@@ -385,9 +385,14 @@ function normalizeStringPosix(path: string, allowAboveRoot: boolean) {
   return res
 }
 
+function formatExt(ext: string | undefined) {
+  if (!ext) return ""
+  return ext.startsWith(".") ? ext : `.${ext}`
+}
+
 function _format(sep: string, pathObject: Partial<Path.Parsed>) {
   const dir = pathObject.dir || pathObject.root
-  const base = pathObject.base || (pathObject.name || "") + (pathObject.ext || "")
+  const base = pathObject.base || (pathObject.name || "") + formatExt(pathObject.ext)
   if (!dir) {
     return base
   }