website/docs/Intro.mdx - main - githubmirror/immutable-js

website/docs/Intro.mdx
105 строк4 KB
Julien Deniau
Add Inheritance cheatsheet section
28 май 2025, 01:05
28 май 2025, 01:0568d47ca
Immutable data encourages pure functions (data-in, data-out) and lends itself
to much simpler application development and enabling techniques from
functional programming such as lazy evaluation.

While designed to bring these powerful functional concepts to JavaScript, it
presents an Object-Oriented API familiar to Javascript engineers and closely
mirroring that of Array, Map, and Set. It is easy and efficient to convert to
and from plain Javascript types.

## How to read these docs

In order to better explain what kinds of values the Immutable.js API expects
and produces, this documentation is presented in a statically typed dialect of
JavaScript (like [Flow][] or [TypeScript][]). You _don't need_ to use these
type checking tools in order to use Immutable.js, however becoming familiar
with their syntax will help you get a deeper understanding of this API.

**A few examples and how to read them.**

All methods describe the kinds of data they accept and the kinds of data
they return. For example a function which accepts two numbers and returns
a number would look like this:

```ts
sum(first: number, second: number): number
```

Sometimes, methods can accept different kinds of data or return different
kinds of data, and this is described with a _type variable_, which is
typically in all-caps. For example, a function which always returns the same
kind of data it was provided would look like this:

```ts
identity<T>(value: T): T
```

Type variables are defined with classes and referred to in methods. For
example, a class that holds onto a value for you might look like this:

```ts
class Box<T> {
  constructor(value: T);
  getValue(): T;
}
```

In order to manipulate Immutable data, methods that we're used to affecting
a Collection instead return a new Collection of the same type. The type
`this` refers to the same kind of class. For example, a List which returns
new Lists when you `push` a value onto it might look like:

```ts
class List<T> {
  push(value: T): this;
}
```

Many methods in Immutable.js accept values which implement the JavaScript
[Iterable][] protocol, and might appear like `Iterable<string>` for something
which represents sequence of strings. Typically in JavaScript we use plain
Arrays (`[]`) when an Iterable is expected, but also all of the Immutable.js
collections are iterable themselves!

For example, to get a value deep within a structure of data, we might use
`getIn` which expects an `Iterable` path:

```ts
getIn(path: Iterable<string | number>): unknown
```

To use this method, we could pass an array: `data.getIn([ "key", 2 ])`.

### Inheritance cheatsheet

The following diagram shows the inheritance relationships between the
Immutable.js collections. Click on the image to view it in full size.

<span>
  {/*
  SVG files are generated from https://excalidraw.com/#json=Indmlmx6FxIgZXvBbKbmH,OKX0Xpl-pmU1c8ZQueCj6Q
  If you want to update this chart:
    - open the link above
    - edit the chart
    - export it as SVG via "file > export" without background, one time in light mode and one time in dark mode
    - change the link above with the link you will get with "share > shareable link"
  */}
</span>

<a href="/Immutable.js-Inheritance-cheatsheet.light.excalidraw.svg">
  <picture>
    <source
      srcSet="/Immutable.js-Inheritance-cheatsheet.dark.excalidraw.svg"
      media="(prefers-color-scheme: dark)"
    />
    <img
      src="/Immutable.js-Inheritance-cheatsheet.light.excalidraw.svg"
      alt="Immutable.js Inheritance cheatsheet"
    />
  </picture>
</a>

[ES2015]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla
[TypeScript]: https://www.typescriptlang.org/
[Flow]: https://flowtype.org/
[Iterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols