-
-
Notifications
You must be signed in to change notification settings - Fork 46
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #885 from neet/v6
Masto.js v6
- Loading branch information
Showing
459 changed files
with
9,748 additions
and
9,097 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,4 @@ | ||
| { | ||
| "semi": true, | ||
| "singleQuote": true, | ||
| "trailingComma": "all" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,58 +1,56 @@ | ||
| # Contribution Guideline | ||
|
|
||
| Thank you for considering contribution. Please check following guideline and please make sure that you satisfy the policy. | ||
| ## Introduction | ||
|
|
||
| ## Setup | ||
| Thank you for considering contributions. This document describes the technology used in Masto.js and some useful information. | ||
|
|
||
| 1. Install **Node.js**, **Git** and **Yarn**. | ||
| 2. Clone this repository by `git clone` | ||
| 3. Run `yarn install` to install dependencies | ||
| I will assume that you have basic TypeScript knowledge, so if you want to learn from the basics, I recommend that you refer to the official TypeScript or Node.js documentation. | ||
|
|
||
| ## Project Structure | ||
| ## Technology and Tips | ||
|
|
||
| Our project in organized under the following directory structure. | ||
| ### Mastodon Types and Proxy API | ||
|
|
||
| ``` | ||
| ./src | ||
| ├── mastodon TypeScript representation of Mastodon API. | ||
| │ │ This directory is public under the namespace `mastodon` and does not contain library-specific code | ||
| │ ├── v1 | ||
| │ │ ├── entities V1 response types | ||
| │ │ └── repositories V1 resource classes | ||
| │ └── v2 | ||
| │ ├── entities V2 response types | ||
| │ └── repositories V2 resource classes | ||
| ├── errors Error classes | ||
| ├── http HTTP wrapper | ||
| ├── logger Logging service | ||
| ├── serializers Service to encode requests or decode responses | ||
| ├── utils General utilities | ||
| └── ws Websocket wrapper | ||
| ``` | ||
| In principle, Masto.js contains as little runtime code as possible in order to reduce bundle size. | ||
|
|
||
| All accesses to the Mastodon API (`masto.v1.statuses.create`, `masto.v1.accounts.$select`, etc.) are interpreted by a [Proxy object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) and converted into an abstract object called `Action`. | ||
|
|
||
| The `Action` is converted to the corresponding URL in the layer described below, and the request is sent. | ||
|
|
||
| ### Architecture | ||
|
|
||
| The architecture follows the class diagram below. In principle, interfaces and implementations are separated, with interfaces placed under `src/interfaces` and implementations placed in `src/adapters`. | ||
|
|
||
| ### Repository | ||
| [](https://mermaid.live/edit#pako:eNqlVU1v4jAQ_SvIp5YC4qMhbIQqVUWr7aGrajlUWuVinAGsJnZqTxAU8d_XSWCbDyeLtLkkmryZNzNvxj4SJgMgHmEh1XrB6UbRyBcd82SWzhIUpyH_BNU55vb0mc-5QFBryuDh4ct8py_om9uCNYCa_VTkeGTIpVhwHVNk2-uYgjP6hmbOt95O8sAS-w1WS8neAZ-kWPPNNaEVaBnu4JXitlTGBvCF7h8RIYpRWyv5gRj_P1EEagO_4CMBjc-C4xvH7QLWNAlbaK8hNBWUiGKpK4aspWXtQkC7bMXWCmAorxKOso-Eq_KAsFDqf3Ask5Vmisep2EWaux0NTZ9K4RKhc_SqGNQ-1T8p8h08R3FYn8hXJfeHElm1gTSOw0OjJNW5rv63c_8tuc293vs8TI4pLO2832-pNhucFGJLx6JvCm2ibnDp97t2FXOP2u5fsrFXb4W3dOyrzJpn13gWdC40pNuaQiObPaKlJd32nCsKdhvkKZw1TZBKlGuVu4RsH7J8EJ9CDgK_0_RveVeYAor1BSyu1nwwKAdoalnK24QuF96Esu2ADesL0iPmAI4oD8y1mBXkE9xCBD7xzGdA1btPfHEyOJqgXB4EIx6qBHokiQNT8vkWJd6ahtpYYyqIdyR74o2mo4F77w4njvNtNnSGbo8ciDd2p4PZaOaMncnMcd3RxDn1yKeUJsJw4M6G4-nY-Izvncl0NOkRCLhJ9eV8baevjOJ35pDmcfoDWe-DdQ) | ||
|
|
||
| _Repository_ is a class for representing REST resources. They have several methods and multiple implementations, all named according to the following convention. Let `x` is the name of a resource. | ||
| The main classes are described as follows | ||
|
|
||
| | URL Pattern | Method Name | Parameter Name | | ||
| | ------------------------------ | ---------------- | ----------------- | | ||
| | `GET /api/v1/x` | `v1.x.list` | `ListXParams` | | ||
| | `GET /api/v1/x/:id` | `v1.x.fetch` | `FetchXParams` | | ||
| | `POST /api/v1/x` | `v1.x.create` | `CreateXParams` | | ||
| | `POST /api/v1/x/:id/{verb}` | `v1.x.do` (verb) | `DoXParams` | | ||
| | `GET /api/v1/x/:id/{sub}` | `v1.x.listSub` | `ListXSubParams` | | ||
| | `GET /api/v1/x/:id/{sub}/:id2` | `v1.x.fetchSub` | `FetchXSubParams` | | ||
| | `DELETE /api/v1/x/:id` | `v1.x.remove` | `RemoveXParams` | | ||
| | `PUT or PATCH /api/v1/x/:id` | `v1.x.update` | `UpdateXParams` | | ||
| - `Serializer` - A class that converts from JavaScript objects to formats such as JSON and FormData, and vice versa. In addition, the conversion from SnakeCase to CamelCase is performed here. | ||
| - `ActionDispatcher` - In Masto.js, streaming subscriptions, HTTP requests, etc. are treated as abstract `Action` data structures, from which `ActionDispatchers` make the actual request. | ||
| - `Http` - The class that creates the HTTP communication, used to implement `mastodon.rest.Client`. | ||
| - `WebSocketConnector`: class for creating WebSocket instances, used in the implementation of `mastodon.streaming`. | ||
|
|
||
| ### Testing | ||
|
|
||
| Masto.js uses both E2E tests and unit tests. In principle, we write mainly E2E tests, and use unit tests to cover only those areas that cannot be covered, such as exception handling. | ||
|
|
||
| In the Jest environment for E2E testing, an object called `session` is exposed in the global space, and you can easily obtain a test account by doing the following. | ||
|
|
||
| ```typescript | ||
| // To simulate a single user | ||
| sessions.use(async session => { | ||
| await session.rest.v1.statuses.$select("123").fetch(); | ||
| }); | ||
|
|
||
| // To simulate an interaction between two users | ||
| sessions.use(2, async ([alice, bob]) => { | ||
| await alice.rest.v1.statuses.create({ | ||
| `Hello @${bob.account.acct}` | ||
| }) | ||
| }); | ||
| ``` | ||
| ## Scripts | ||
| The tests are automatically run by CI, but if you need to check them locally, please refer to the GitHub Actions workflow in the repository to set up your environment. For other ways to write tests, please refer to the official Jest documentation. | ||
| There are some useful scripts in `package.json` which you can with `yarn run`. | ||
| ## Review and Releases | ||
| - `test:jest` - Jest unit testing | ||
| - `test:eslint` - Lints the codes with ESLint (includes Prettier) | ||
| - `test:spellcheck` - Lints the codes with CSpell | ||
| - `test` - Run all tests | ||
| - `build` - Build the source code with Rollup | ||
| - `prepublishOnly` - Automatically runs before `npm publish` | ||
| - `docs:build` - Generate documentation by TypeDoc | ||
| Once you have verified your changes locally, create a Pull Request and have it reviewed by the author. If your changes are merged, they will be automatically released by the following 0:00 UTC. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.