diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index fcd10b9..c035b28 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -32,6 +32,8 @@ jobs: run: deno fmt --check - name: Type check run: deno task check + - name: Test doc + run: deno task test jsr-publish: runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fff3a34 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +deno.lock diff --git a/README.md b/README.md index e9d2ff1..2055127 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,31 @@ # 🪐 denops_core [![JSR](https://jsr.io/badges/@denops/core)](https://jsr.io/@denops/core) -[![denoland](https://img.shields.io/github/v/release/vim-denops/deno-denops-core?logo=deno&label=denoland)](https://deno.land/x/denops_core) -[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/denops_core/mod.ts) [![test](https://github.com/vim-denops/deno-denops/workflows/test/badge.svg)](https://github.com/vim-denops/deno-denops/actions?query=workflow%3Atest) -This module is a fundamental component of [denops.vim], an ecosystem for -crafting plugins in [Deno] for Vim/Neovim. +This is a core module of [denops.vim], an ecosystem for creating Vim/Neovim +plugin in [Deno]. -It's essential to highlight that the recommended practice for most users is to -utilize the [denops_std] module when developing plugins for [denops.vim]. The -current module is structured as a foundational layer within [denops_std], and -utilizing it directly from plugins is **strongly discouraged**. +> [!WARNING] +> +> This module is mainly for internal use. It's **strongly discouraged** to +> utilize this module directly from plugins. Use the [@denops/std] module +> instead. + +```ts +import type { Entrypoint } from "jsr:@denops/core"; + +export const main: Entrypoint = (denops) => { + // ... +}; +``` [deno]: https://deno.land/ [denops.vim]: https://github.com/vim-denops/denops.vim -[denops_std]: https://deno.land/x/denops_std +[@denops/std]: https://jsr.io/@denops/std + +# License + +The code follows the MIT license, as stated in [LICENSE](./LICENSE). +Contributors need to agree that any modifications sent to this repository follow +the license. diff --git a/deno.jsonc b/deno.jsonc index ccfcc3f..9054ca8 100644 --- a/deno.jsonc +++ b/deno.jsonc @@ -11,6 +11,6 @@ "update:commit": "deno task -q update --commit --pre-commit=fmt,lint" }, "imports": { - "https://deno.land/x/denops_core@$MODULE_VERSION/": "./" + "jsr:@denops/core": "./mod.ts" } } diff --git a/denops.ts b/denops.ts index 18bfe25..d0872ed 100644 --- a/denops.ts +++ b/denops.ts @@ -74,6 +74,11 @@ export interface Denops { */ readonly context: Record; + /** + * AbortSignal instance that is triggered when the user invoke `denops#interrupt()` + */ + readonly interrupted?: AbortSignal; + /** * User-defined API name and method map used to dispatch API requests. */ @@ -142,14 +147,32 @@ export interface Denops { /** * Denops's entrypoint definition. * - * Use this type to ensure the `main` function is properly implemented like + * Use this type to ensure the `main` function is properly implemented like: + * + * ```ts + * import type { Entrypoint } from "jsr:@denops/core"; + * + * export const main: Entrypoint = (denops) => { + * // ... + * } + * ``` + * + * If an `AsyncDisposable` object is returned, resources can be disposed of + * asynchronously when the plugin is unloaded, like: * * ```ts - * import type { Entrypoint } from "https://deno.land/x/denops_core@$MODULE_VERSION/mod.ts"; + * import type { Entrypoint } from "jsr:@denops/core"; * * export const main: Entrypoint = (denops) => { * // ... + * return { + * [Symbol.asyncDispose]: async () => { + * // Dispose resources... + * } + * } * } * ``` */ -export type Entrypoint = (denops: Denops) => void | Promise; +export type Entrypoint = ( + denops: Denops, +) => void | AsyncDisposable | Promise; diff --git a/mod.ts b/mod.ts index 803fdbc..9f1ec4a 100644 --- a/mod.ts +++ b/mod.ts @@ -1,12 +1,24 @@ /** - * This module is a fundamental component of [denops.vim], an ecosystem for crafting plugins in [Deno] for Vim/Neovim. + * This is a core module of [denops.vim], an ecosystem for creating Vim/Neovim + * plugin in [Deno]. * - * It's essential to highlight that the recommended practice for most users is to utilize the [denops_std] module when developing plugins for [denops.vim]. - * The current module is structured as a foundational layer within [denops_std], and utilizing it directly from plugins is **strongly discouraged**. + * > [!WARNING] + * > + * > This module is mainly for internal use. It's **strongly discouraged** to + * > utilize this module directly from plugins. Use the [@denops/std] module + * > instead. + * + * ```ts + * import type { Entrypoint } from "jsr:@denops/core"; + * + * export const main: Entrypoint = (denops) => { + * // ... + * }; + * ``` * * [deno]: https://deno.land/ * [denops.vim]: https://github.com/vim-denops/denops.vim - * [denops_std]: https://deno.land/x/denops_std + * [@denops/std]: https://jsr.io/@denops/std * * @module */