已发布 上游基线 bf46254 原文 ↗ 在 GitHub 编辑

导入 Effect

通过安装 effect 包并导入必要的模块与函数,开始用 Effect 构建类型安全、模块化的应用。

如果你刚刚入门,可能会被 Effect 提供的众多模块和函数弄得不知所措。

不过请放心,你并不需要马上就把它们全部搞懂。

本页会简单介绍如何导入模块与函数,并说明:开始使用时,通常只需要安装 effect 包就够了。

安装 Effect

如果你还没有安装 effect 包,可以在终端中运行下面的命令来安装:

npm
npm install effect
pnpm
pnpm add effect
Yarn
yarn add effect
Bun
bun add effect
Deno
deno add npm:effect

安装这个包之后,你就可以使用 Effect 的核心功能。

如果你想了解 Deno、Bun 等平台的详细安装说明,请参阅 安装 指南,其中提供了逐步的操作指引。

导入模块与函数

安装好 effect 包之后,你就可以在项目中使用它的模块和函数了。 导入模块与函数非常直接,遵循标准的 JavaScript/TypeScript 导入语法。

要从 effect 包中导入某个模块或函数,只需在文件顶部使用 import 语句。下面演示如何导入 Effect 模块:

import { Effect } from "effect"

现在你就可以使用 Effect 模块了,它是 Effect 库的核心。它提供了各种函数,用于创建、组合和操作带 effect 的计算。

命名空间导入

除了像前面那样用命名导入的方式导入 Effect 模块之外:

import { Effect } from "effect"

你还可以用命名空间导入的方式这样写:

import * as Effect from "effect/Effect"

这两种导入方式都能让你使用 Effect 模块提供的功能。

不过有一个重要的考量:tree shaking(摇树优化),它指的是在打包应用的过程中剔除未使用代码的过程。 当打包工具不支持深层作用域分析时,命名导入可能会带来 tree shaking 问题。

以下这些打包工具支持深层作用域分析,因此命名导入不会有问题:

  • Rolldown
  • Rollup
  • Webpack 5+

函数与方法

在 Effect 生态中,库通常暴露的是函数而不是方法。这一设计选择之所以重要,有两个关键原因:tree shaking 的友好性与可扩展性。

Tree shaking 友好性

Tree shaking 友好性是指构建系统在打包过程中剔除未使用代码的能力。函数可以被 tree shaking 剔除,而方法不行。

在 Effect 生态中使用函数时,只有那些真正被导入并在应用中用到的函数才会被包含进最终打包的代码里。未使用的函数会被自动移除,从而减小打包体积、提升性能。

另一方面,方法依附在对象或原型上,很难被 tree shaking 剔除。即使你只用到其中一部分方法,与该对象或原型关联的所有方法都会被放进打包结果,造成不必要的代码膨胀。

可扩展性

在 Effect 生态中使用函数还有一个重要优势:易于扩展。如果使用方法,想扩展某个现有 API 的功能往往需要修改对象的原型,这既复杂又容易出错。

相比之下,使用函数时扩展功能要简单得多。你可以把自己的「扩展方法」定义为普通的函数,而无需修改对象的原型。这有助于写出更清晰、更模块化的代码,也能更好地与其他库和模块兼容。

常用函数

当你开始 Effect 之旅时,并不需要立刻钻研 effect 包里的每一个函数。相反,先专注于一些常用函数,它们会为你的 Effect 世界之旅打下坚实的基础。

在接下来的指南中,我们会探讨其中一些必不可少的函数,特别是用于创建和运行 Effect 以及构建管道的那些函数。

但在深入这些内容之前,让我们从 Effect 的核心开始:理解 Effect 类型。这将为你理解 Effect 如何把可组合性、类型安全和错误处理带进你的应用打下基础。

那么,让我们迈出第一步,探索 Effect 类型 的基础概念。