@effect/platform 0.0.0 → 0.2.0

package/src/FileSystem.ts

@@ -1,16 +1,231 @@
 /**
  * @since 1.0.0
  */
-import type * as Brand from "@effect/data/Brand"
+import * as Brand from "@effect/data/Brand"
 import type { Tag } from "@effect/data/Context"
+import type { Option } from "@effect/data/Option"
 import type * as Effect from "@effect/io/Effect"
 import type { Scope } from "@effect/io/Scope"
 import type { PlatformError } from "@effect/platform/Error"
-import type { File } from "@effect/platform/FileSystem/File"
 import * as internal from "@effect/platform/internal/fileSystem"
 import type { Sink } from "@effect/stream/Sink"
 import type { Stream } from "@effect/stream/Stream"
 
+/**
+ * @since 1.0.0
+ * @category model
+ */
+export interface FileSystem {
+  /**
+   * Check if a file can be accessed.
+   * You can optionally specify the level of access to check for.
+   */
+  readonly access: (
+    path: string,
+    options?: AccessFileOptions
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Copy a file or directory from `fromPath` to `toPath`.
+   *
+   * Equivalent to `cp -r`.
+   */
+  readonly copy: (
+    fromPath: string,
+    toPath: string,
+    options?: CopyOptions
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Copy a file from `fromPath` to `toPath`.
+   */
+  readonly copyFile: (
+    fromPath: string,
+    toPath: string
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Change the permissions of a file.
+   */
+  readonly chmod: (
+    path: string,
+    mode: number
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Change the owner and group of a file.
+   */
+  readonly chown: (
+    path: string,
+    uid: number,
+    gid: number
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Create a hard link from `fromPath` to `toPath`.
+   */
+  readonly link: (
+    fromPath: string,
+    toPath: string
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Create a directory at `path`. You can optionally specify the mode and
+   * whether to recursively create nested directories.
+   */
+  readonly makeDirectory: (
+    path: string,
+    options?: MakeDirectoryOptions
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Create a temporary directory.
+   *
+   * By default the directory will be created inside the system's default
+   * temporary directory, but you can specify a different location by setting
+   * the `directory` option.
+   *
+   * You can also specify a prefix for the directory name by setting the
+   * `prefix` option.
+   */
+  readonly makeTempDirectory: (
+    options?: MakeTempDirectoryOptions
+  ) => Effect.Effect<never, PlatformError, string>
+  /**
+   * Create a temporary directory inside a scope.
+   *
+   * Functionally equivalent to `makeTempDirectory`, but the directory will be
+   * automatically deleted when the scope is closed.
+   */
+  readonly makeTempDirectoryScoped: (
+    options?: MakeTempDirectoryOptions
+  ) => Effect.Effect<Scope, PlatformError, string>
+  /**
+   * Create a temporary file.
+   * The directory creation is functionally equivalent to `makeTempDirectory`.
+   * The file name will be a randomly generated string.
+   */
+  readonly makeTempFile: (
+    options?: MakeTempFileOptions
+  ) => Effect.Effect<never, PlatformError, string>
+  /**
+   * Create a temporary file inside a scope.
+   *
+   * Functionally equivalent to `makeTempFile`, but the file will be
+   * automatically deleted when the scope is closed.
+   */
+  readonly makeTempFileScoped: (
+    options?: MakeTempFileOptions
+  ) => Effect.Effect<Scope, PlatformError, string>
+  /**
+   * Open a file at `path` with the specified `options`.
+   *
+   * The file handle will be automatically closed when the scope is closed.
+   */
+  readonly open: (
+    path: string,
+    options?: OpenFileOptions
+  ) => Effect.Effect<Scope, PlatformError, File>
+  /**
+   * List the contents of a directory.
+   *
+   * You can recursively list the contents of nested directories by setting the
+   * `recursive` option.
+   */
+  readonly readDirectory: (
+    path: string,
+    options?: ReadDirectoryOptions
+  ) => Effect.Effect<never, PlatformError, ReadonlyArray<string>>
+  /**
+   * Read the contents of a file.
+   */
+  readonly readFile: (
+    path: string
+  ) => Effect.Effect<never, PlatformError, Uint8Array>
+  /**
+   * Read the destination of a symbolic link.
+   */
+  readonly readLink: (
+    path: string
+  ) => Effect.Effect<never, PlatformError, string>
+  /**
+   * Resolve a path to its canonicalized absolute pathname.
+   */
+  readonly realPath: (
+    path: string
+  ) => Effect.Effect<never, PlatformError, string>
+  /**
+   * Remove a file or directory.
+   *
+   * By setting the `recursive` option to `true`, you can recursively remove
+   * nested directories.
+   */
+  readonly remove: (
+    path: string,
+    options?: RemoveOptions
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Rename a file or directory.
+   */
+  readonly rename: (
+    oldPath: string,
+    newPath: string
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Create a writable `Sink` for the specified `path`.
+   */
+  readonly sink: (
+    path: string,
+    options?: SinkOptions
+  ) => Sink<never, PlatformError, Uint8Array, never, void>
+  /**
+   * Get information about a file at `path`.
+   */
+  readonly stat: (
+    path: string
+  ) => Effect.Effect<never, PlatformError, File.Info>
+  /**
+   * Create a readable `Stream` for the specified `path`.
+   *
+   * Changing the `bufferSize` option will change the internal buffer size of
+   * the stream. It defaults to `4`.
+   *
+   * The `chunkSize` option will change the size of the chunks emitted by the
+   * stream. It defaults to 64kb.
+   *
+   * Changing `offset` and `bytesToRead` will change the offset and the number
+   * of bytes to read from the file.
+   */
+  readonly stream: (
+    path: string,
+    options?: StreamOptions
+  ) => Stream<never, PlatformError, Uint8Array>
+  /**
+   * Create a symbolic link from `fromPath` to `toPath`.
+   */
+  readonly symlink: (
+    fromPath: string,
+    toPath: string
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Truncate a file to a specified length. If the `length` is not specified,
+   * the file will be truncated to length `0`.
+   */
+  readonly truncate: (
+    path: string,
+    length?: Size
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Change the file system timestamps of the file at `path`.
+   */
+  readonly utimes: (
+    path: string,
+    atime: Date | number,
+    mtime: Date | number
+  ) => Effect.Effect<never, PlatformError, void>
+  /**
+   * Write data to a file at `path`.
+   */
+  readonly writeFile: (
+    path: string,
+    data: Uint8Array,
+    options?: WriteFileOptions
+  ) => Effect.Effect<never, PlatformError, void>
+}
+
 /**
  * Represents a size in bytes.
  *
@@ -29,6 +244,22 @@ export const Size: (bytes: number | bigint) => Size = internal.Size
  * @since 1.0.0
  * @category model
  */
+export type OpenFlag =
+  | "r"
+  | "r+"
+  | "w"
+  | "wx"
+  | "w+"
+  | "wx+"
+  | "a"
+  | "ax"
+  | "a+"
+  | "ax+"
+
+/**
+ * @since 1.0.0
+ * @category options
+ */
 export interface AccessFileOptions {
   readonly ok?: boolean
   readonly readable?: boolean
@@ -37,7 +268,7 @@ export interface AccessFileOptions {
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
 export interface MakeDirectoryOptions {
   readonly recursive?: boolean
@@ -46,41 +277,34 @@ export interface MakeDirectoryOptions {
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
-export interface MakeTempDirectoryOptions {
-  readonly directory?: string
-  readonly prefix?: string
+export interface CopyOptions {
+  readonly overwrite?: boolean
+  readonly preserveTimestamps?: boolean
 }
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
-export interface MakeTempFileOptions {
+export interface MakeTempDirectoryOptions {
   readonly directory?: string
   readonly prefix?: string
 }
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
-export type OpenFlag =
-  | "r"
-  | "r+"
-  | "w"
-  | "wx"
-  | "w+"
-  | "wx+"
-  | "a"
-  | "ax"
-  | "a+"
-  | "ax+"
+export interface MakeTempFileOptions {
+  readonly directory?: string
+  readonly prefix?: string
+}
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
 export interface OpenFileOptions {
   readonly flag?: OpenFlag
@@ -89,7 +313,7 @@ export interface OpenFileOptions {
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
 export interface ReadDirectoryOptions {
   readonly recursive?: boolean
@@ -97,7 +321,7 @@ export interface ReadDirectoryOptions {
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
 export interface RemoveOptions {
   readonly recursive?: boolean
@@ -105,133 +329,146 @@ export interface RemoveOptions {
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
 export interface SinkOptions extends OpenFileOptions {}
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
 export interface StreamOptions {
-  bufferSize?: number
-  bytesToRead?: Size
-  chunkSize?: Size
-  offset?: Size
+  readonly bufferSize?: number
+  readonly bytesToRead?: Size
+  readonly chunkSize?: Size
+  readonly offset?: Size
 }
 
 /**
  * @since 1.0.0
- * @category model
+ * @category options
  */
 export interface WriteFileOptions {
   readonly flag?: OpenFlag
   readonly mode?: number
 }
 
+/**
+ * @since 1.0.0
+ * @category tag
+ */
+export const FileSystem: Tag<FileSystem, FileSystem> = internal.tag
+
+/**
+ * @since 1.0.0
+ * @category constructor
+ */
+export const make: (impl: Omit<FileSystem, "stream" | "sink">) => FileSystem = internal.make
+
+/**
+ * @since 1.0.0
+ * @category type id
+ */
+export const FileTypeId: unique symbol = Symbol.for(
+  "@effect/platform/FileSystem/File"
+)
+
+/**
+ * @since 1.0.0
+ * @category type id
+ */
+export type FileTypeId = typeof FileTypeId
+
+/**
+ * @since 1.0.0
+ * @category guard
+ */
+export const isFile = (u: unknown): u is File => typeof u === "object" && u !== null && FileTypeId in u
+
 /**
  * @since 1.0.0
  * @category model
  */
-export interface FileSystem {
-  readonly access: (
-    path: string,
-    options?: AccessFileOptions
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly copyFile: (
-    fromPath: string,
-    toPath: string
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly chmod: (
-    path: string,
-    mode: number
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly chown: (
-    path: string,
-    uid: number,
-    gid: number
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly link: (
-    fromPath: string,
-    toPath: string
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly makeDirectory: (
-    path: string,
-    options?: MakeDirectoryOptions
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly makeTempDirectory: (
-    options?: MakeTempDirectoryOptions
-  ) => Effect.Effect<never, PlatformError, string>
-  readonly makeTempDirectoryScoped: (
-    options?: MakeTempDirectoryOptions
-  ) => Effect.Effect<Scope, PlatformError, string>
-  readonly makeTempFile: (
-    options?: MakeTempFileOptions
-  ) => Effect.Effect<Scope, PlatformError, File>
-  readonly open: (
-    path: string,
-    options?: OpenFileOptions
-  ) => Effect.Effect<Scope, PlatformError, File>
-  readonly readDirectory: (
-    path: string,
-    options?: ReadDirectoryOptions
-  ) => Effect.Effect<never, PlatformError, ReadonlyArray<string>>
-  readonly readFile: (
-    path: string
-  ) => Effect.Effect<never, PlatformError, Uint8Array>
-  readonly readLink: (
-    path: string
-  ) => Effect.Effect<never, PlatformError, string>
-  readonly realPath: (
-    path: string
-  ) => Effect.Effect<never, PlatformError, string>
-  readonly remove: (
-    path: string,
-    options?: RemoveOptions
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly rename: (
-    oldPath: string,
-    newPath: string
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly sink: (
-    path: string,
-    options?: SinkOptions
-  ) => Sink<never, PlatformError, Uint8Array, never, void>
-  readonly stat: (
-    path: string
-  ) => Effect.Effect<never, PlatformError, File.Info>
-  readonly stream: (
-    path: string,
-    options?: StreamOptions
-  ) => Stream<never, PlatformError, Uint8Array>
-  readonly symlink: (
-    fromPath: string,
-    toPath: string
-  ) => Effect.Effect<never, PlatformError, void>
+export interface File {
+  readonly [FileTypeId]: (_: never) => unknown
+  readonly fd: File.Descriptor
+  readonly stat: Effect.Effect<never, PlatformError, File.Info>
+  readonly read: (
+    buffer: Uint8Array,
+    options?: FileReadOptions
+  ) => Effect.Effect<never, PlatformError, Size>
+  readonly readAlloc: (
+    size: Size,
+    options?: FileReadOptions
+  ) => Effect.Effect<never, PlatformError, Option<Uint8Array>>
   readonly truncate: (
-    path: string,
     length?: Size
   ) => Effect.Effect<never, PlatformError, void>
-  readonly utime: (
-    path: string,
-    atime: Date | number,
-    mtime: Date | number
-  ) => Effect.Effect<never, PlatformError, void>
-  readonly writeFile: (
-    path: string,
-    data: Uint8Array,
-    options?: WriteFileOptions
+  readonly write: (
+    buffer: Uint8Array
+  ) => Effect.Effect<never, PlatformError, Size>
+  readonly writeAll: (
+    buffer: Uint8Array
   ) => Effect.Effect<never, PlatformError, void>
 }
 
 /**
  * @since 1.0.0
- * @category tag
  */
-export const FileSystem: Tag<FileSystem, FileSystem> = internal.tag
+export namespace File {
+  /**
+   * @since 1.0.0
+   * @category model
+   */
+  export type Descriptor = Brand.Branded<number, "FileDescriptor">
+
+  /**
+   * @since 1.0.0
+   * @category model
+   */
+  export type Type =
+    | "File"
+    | "Directory"
+    | "SymbolicLink"
+    | "BlockDevice"
+    | "CharacterDevice"
+    | "FIFO"
+    | "Socket"
+    | "Unknown"
+
+  /**
+   * @since 1.0.0
+   * @category model
+   */
+  export interface Info {
+    readonly type: Type
+    readonly mtime: Option<Date>
+    readonly atime: Option<Date>
+    readonly birthtime: Option<Date>
+    readonly dev: number
+    readonly ino: Option<number>
+    readonly mode: number
+    readonly nlink: Option<number>
+    readonly uid: Option<number>
+    readonly gid: Option<number>
+    readonly rdev: Option<number>
+    readonly size: Size
+    readonly blksize: Option<Size>
+    readonly blocks: Option<number>
+  }
+}
 
 /**
  * @since 1.0.0
  * @category constructor
  */
-export const make: (impl: Omit<FileSystem, "stream" | "sink">) => FileSystem = internal.make
+export const FileDescriptor = Brand.nominal<File.Descriptor>()
+
+/**
+ * @since 1.0.0
+ * @category model
+ */
+export interface FileReadOptions {
+  readonly offset?: Size
+  readonly length?: Size
+}

package/src/Path.ts

@@ -0,0 +1,64 @@
+/**
+ * @since 1.0.0
+ */
+
+import type { Tag } from "@effect/data/Context"
+import type { Effect } from "@effect/io/Effect"
+import type { Layer } from "@effect/io/Layer"
+import type { BadArgument } from "@effect/platform/Error"
+import * as internal from "@effect/platform/internal/path"
+
+/**
+ * @since 1.0.0
+ * @category model
+ */
+export interface Path {
+  readonly sep: string
+  readonly basename: (path: string, suffix?: string) => string
+  readonly dirname: (path: string) => string
+  readonly extname: (path: string) => string
+  readonly format: (pathObject: Partial<Path.Parsed>) => string
+  readonly fromFileUrl: (url: URL) => Effect<never, BadArgument, string>
+  readonly isAbsolute: (path: string) => boolean
+  readonly join: (...paths: ReadonlyArray<string>) => string
+  readonly normalize: (path: string) => string
+  readonly parse: (path: string) => Path.Parsed
+  readonly relative: (from: string, to: string) => string
+  readonly resolve: (...pathSegments: ReadonlyArray<string>) => string
+  readonly toFileUrl: (path: string) => Effect<never, BadArgument, URL>
+  readonly toNamespacedPath: (path: string) => string
+}
+
+/**
+ * @since 1.0.0
+ */
+export namespace Path {
+  /**
+   * @since 1.0.0
+   * @category model
+   */
+  export interface Parsed {
+    readonly root: string
+    readonly dir: string
+    readonly base: string
+    readonly ext: string
+    readonly name: string
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category tag
+ */
+export const Path: Tag<Path, Path> = internal.Path
+
+/**
+ * An implementation of the Path interface that can be used in all environments
+ * (including browsers).
+ *
+ * It uses the POSIX standard for paths.
+ *
+ * @since 1.0.0
+ * @category layer
+ */
+export const layer: Layer<never, never, Path> = internal.layer