@pulsar-edit/types 1.128.1

package/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+env:
+  NODE_VERSION: 20
+  NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - run: npm ci
+      - run: npm test
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish --access public

package/LICENSE.md

@@ -0,0 +1,8 @@
+This project is licensed under the MIT license.
+Copyrights are respective of each contributor listed at the beginning of each definition file — or failing that, to the Pulsar-Edit team.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# @pulsar-edit/types
+
+Type definitions for the [Pulsar API](https://docs.pulsar-edit.dev/api/pulsar/latest/).
+
+Also includes some type definitions from notable builtin and community packages:
+
+* `autocomplete-plus`
+* `status-bar`
+* `tool-bar`
+* `linter`
+* `atom-i18n`
+
+Migrated from [@types/atom](https://www.npmjs.com/package/@types/atom) and updated to reflect new and changed APIs in Pulsar.
+
+Install these types under `devDependencies` if you’re writing a community package in TypeScript or JavaScript. Pair this package with [`pulsar-ide-typescript`](https://packages.pulsar-edit.dev/packages/pulsar-ide-typescript) for better autocompletion and inline method descriptions.
+
+## Usage
+
+### Quick (with some sorcery)
+
+Install this package as a `devDependency` and tell it to **pretend** to be `@types/atom`:
+
+```shell
+npm install -D @types/atom@npm:@pulsar-edit/types
+```
+
+This will
+
+* install this package at `./node_modules/@types/atom`, thus giving it all of the built-in privileges of `@types/` packages in the TypeScript environment;
+* make this package’s declarations ambiently available — for instance, the `atom` global;
+* make it so you can import from `atom` — or, for the ancillary types, from `atom/autocomplete-plus`, `atom/linter`, and so on.
+
+If you need to opt into a specific version of `@pulsar-edit/types`, you may add it at the end:
+
+```shell
+npm install -D @types/atom@npm:@pulsar-edit/types@1.130
+```
+
+### Special cases
+
+#### Transitive dependencies
+
+If you depend on something that’s still trying to import `@types/atom` directly, the packages’ ambient declarations will conflict. (`atom-ide-base` and `atom-jasmine3-test-runner` are notable examples.)
+
+If you’re using `npm`, this can be fixed via [the `overrides` section in `package.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides). You can specify that any references to `@types/atom`, no matter the depth, should be fulfilled by this package instead:
+
+```json
+{
+  "overrides": {
+    "@types/atom": "@pulsar-edit/types"
+  }
+}
+```
+
+[Yarn](https://yarnpkg.com/) can do a similar thing with its [`resolutions` property](https://yarnpkg.com/configuration/manifest#resolutions). Ultimately, anything that puts this package at `./node_modules/@types/atom` within the project will suffice.
+
+### Less sorcery
+
+If, for whatever reason, you don’t want to do what’s described above, you can achieve a similar effect solely via `tsconfig.json`.
+
+#### Path remapping
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "atom": ["./node_modules/@pulsar-edit/types"]
+    }
+  }
+}
+```
+
+The [`paths` entry](https://www.typescriptlang.org/tsconfig/#paths) for `atom` tells TypeScript that all references to `atom` in import specifiers can be resolved at the given location on disk.
+
+This is fine because we don’t ever install an `atom` package. During development, references to `atom` will be resolved using these type definitions; at runtime, references to `atom` will be magically resolved by Pulsar.
+
+#### Visibility
+
+One drawback with this approach is that you don’t get _automatic_ “visibility” of this package, meaning its ambient declarations aren’t necessarily present. (Whereas `@types/atom` is automatically visible using TypeScript’s default settings, since it’s a `@types/` package.)
+
+For instance, suppose this is your entire source code:
+
+```ts
+function activate() {
+  atom.beep();
+//^^^^ Cannot find name 'atom'.
+}
+```
+
+This will fix itself once you import something…
+
+```ts
+import { TextEditor } from 'atom';
+
+function activate() {
+  atom.beep();
+}
+```
+
+…or if you toss in a triple-slash directive. (The directive doesn’t follow our remapped path, so you must use the unaliased name of the package.)
+
+```ts
+/// <reference types="@pulsar-edit/types" />
+
+function activate() {
+  atom.beep();
+}
+```
+
+You could also fix this via your `tsconfig.json`…
+
+```json
+"compilerOptions": {
+  "types": ["@pulsar-edit/types"],
+  "paths": {
+    "atom": ["./node_modules/@pulsar-edit/types"]
+  }
+}
+```
+
+…but, in doing so, you opt out of the automatic visibility of `@types/` packages, thus obligating you to reference them all manually. See the `tsconfig.json` documentation for [`types`](https://www.typescriptlang.org/tsconfig/#types) and [`typeRoots`](https://www.typescriptlang.org/tsconfig/#typeRoots) for more information.
+
+
+##### Ancillary types
+
+This `tsconfig.json`-only approach doesn’t give you the ancillary types from various packages…
+
+```ts
+import type { AnySuggestion } from 'atom/autocomplete-plus';
+//            ^^^^^^^^^^^^^ Cannot find name `AnySuggestion`.
+```
+
+…but that’s fine. In this example, `atom/autocomplete-plus` isn’t a valid import specifier at runtime, so you’d only ever use that syntax to import types. Hence you can instead just import directly from `@pulsar-edit/types`:
+
+```ts
+import type { AnySuggestion } from '@pulsar-edit/types/autocomplete-plus';
+```
+
+Still, if you _really_ wanted to make this example available at `atom/autocomplete-plus`, you could add that import specifier to your `tsconfig.json` as well:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "atom": ["./node_modules/@pulsar-edit/types"],
+      "atom/autocomplete-plus": [
+        "./node_modules/@pulsar-edit/types/autocomplete-plus"
+      ]
+    }
+  }
+}
+```
+
+## Versioning
+
+### Minor versions
+
+We will try to update this package at least as often as we update Pulsar, even if there are no API changes from one minor version to another.
+
+If, somehow, this doesn’t happen, it means that the next-lowest version number to exist is the version of `@pulsar-edit/types` that should be used for whichever version of Pulsar you’re targeting. Hence if you’re targeting `1.129.0`, but the latest release of this package is `1.128.0`, then `1.128.0` is the correct version to use.
+
+### Patch versions
+
+Pulsar increments the minor version number with each regular release. If the last release was `1.129.0`, the next regular release will be `1.130.0`. If Pulsar needs to do a bugfix release in between — for instance, if there were an regression in the last regular release — then the patch version number will increment (e.g., `1.129.0` is followed by `1.129.1`).
+
+The version numbers in this repository are designed to harmonize with Pulsar’s version numbers, but **only so far as the minor version**. That’s because this repository may need to update more often than Pulsar itself.
+
+Suppose a version `1.131.1` exists of Pulsar and is the most recent release in the `1.131` range. To target this version of Pulsar, you should install this types package with
+
+```shell
+npm install -D @types/atom@npm:@pulsar-edit/types@1.131
+```
+
+to ensure you’re getting the most recent version of the types that correspond to the `1.131` release. You _should not_ assume that `@pulsar-edit/types` has a `1.131.1` release — or, if it does exist, that it is the “correct” version of this package to install for Pulsar `1.131.1`. The “correct” version to install is the most recent release that starts with `1.131.`.
+
+Pulsar itself will not break API backward-compatibility in a patch release, so patch releases of this package will never be issued in a way that affects backward compatibility. They will always have the effect of describing the current types more accurately.
+
+
+## Questions
+
+### Why isn’t this at `@types/pulsar-edit` or something?
+
+Because Pulsar isn’t delivered as an NPM package. I’m not sure how or why Atom’s API was ever available at `@types/atom`, considering that the NPM package called `atom` has nothing to do with the Atom editor.
+
+### Why not just update `@types/atom`?
+
+We might eventually do that, but this is a suitable workaround for now and frees us from having to negotiate the politics of adopting an orphaned `DefinitelyTyped` package.

package/atom-i18n/config.d.ts

@@ -0,0 +1,9 @@
+// NOTE: intentional; needed for config extensibility
+// eslint-disable-next-line @definitelytyped/no-declare-current-package
+
+declare module "atom" {
+  interface ConfigValues {
+    /** Language for internationalization. */
+    "atom-i18n.locale": string;
+  }
+}

package/atom-i18n/index.d.ts

@@ -0,0 +1,4 @@
+// atom-i18n
+// https://web.pulsar-edit.dev/packages/atom-i18n
+
+/// <reference path="./config.d.ts" />

package/autocomplete-plus/config.d.ts

@@ -0,0 +1,140 @@
+import "../index";
+
+// NOTE: intentional; needed for config extensibility
+// eslint-disable-next-line @definitelytyped/no-declare-current-package
+declare module "atom" {
+  interface ConfigValues {
+    /**
+     * Suggestions will show as you type if this preference is enabled.
+     *
+     * If it is disabled, you can still see suggestions by using the keymapping
+     * for 'autocomplete-plus:activate' (shown below).
+     */
+    "autocomplete-plus.enableAutoActivation": boolean;
+
+    /**
+     * If you are experiencing performance issues when typing, you should try
+     * increasing this value to a non-zero number (e.g. 100).
+     */
+    "autocomplete-plus.autoActivationDelay": number;
+
+    /** The suggestion list will only show this many suggestions. */
+    "autocomplete-plus.maxVisibleSuggestions": number;
+
+    /**
+     * You should use the key(s) indicated here to confirm a suggestion from
+     * the suggestion list and have it inserted into the file.
+     */
+    "autocomplete-plus.confirmCompletion":
+      | "tab"
+      | "enter"
+      | "tab and enter"
+      | "tab always, enter when suggestion explicitly selected";
+
+    /**
+     * Disable this if you want to bind your own keystrokes to move around the
+     * suggestion list. You will also need to add definitions to your keymap.
+     */
+    "autocomplete-plus.useCoreMovementCommands": boolean;
+
+    /**
+     * Suggestions will not be provided for files matching this list — e.g.,
+     * `*.md` for Markdown files.
+     *
+     * To blacklist more than one file extension, use a comma as a separator —
+     * e.g., `["*.md", "*.txt"]` (both Markdown and text files).
+     */
+    "autocomplete-plus.fileBlacklist": string[];
+
+    /** Suggestions will not be provided for scopes matching this list. */
+    "autocomplete-plus.scopeBlacklist": string[];
+
+    /**
+     * For grammars with no registered provider(s), the default provider will
+     * include completions from all buffers, instead of just the buffer you are
+     * currently editing.
+     */
+    "autocomplete-plus.includeCompletionsFromAllBuffers": boolean;
+
+    /**
+     * Fuzzy searching is performed if this is disabled; if it is enabled,
+     * suggestions must begin with the prefix from the current word.
+     */
+    "autocomplete-plus.strictMatching": boolean;
+
+    /**
+     * Only autocomplete when you've typed at least this many characters.
+     *
+     * Note: May not affect external providers.
+     */
+    "autocomplete-plus.minimumWordLength": number;
+
+    /**
+     * The package comes with a built-in provider that will provide suggestions
+     * using the words in your current buffer or all open buffers. You will get
+     * better suggestions by installing additional autocomplete+ providers. To
+     * stop using the built-in provider, disable this option.
+     */
+    "autocomplete-plus.enableBuiltinProvider": boolean;
+
+    /** Don't use the built-in provider for these selector(s). */
+    "autocomplete-plus.builtinProviderBlacklist": string;
+
+    /**
+     * If enabled, typing `backspace` will show the suggestion list if
+     * suggestions are available. If disabled, suggestions will not be shown
+     * while backspacing.
+     */
+    "autocomplete-plus.backspaceTriggersAutocomplete": boolean;
+
+    /**
+     * If enabled, automatically insert suggestion on manual activation with
+     * 'autocomplete-plus:activate' when there is only one match.
+     */
+    "autocomplete-plus.enableAutoConfirmSingleSuggestion": boolean;
+
+    /**
+     * With 'Cursor' the suggestion list appears at the cursor's position.
+     *
+     * With 'Word' it appears at the beginning of the word that's being
+     * completed.
+     */
+    "autocomplete-plus.suggestionListFollows": "Word" | "Cursor";
+
+    /**
+     * If you're having trouble with autocomplete, you may consider falling
+     * back to the Symbol provider and filing an issue.
+     */
+    "autocomplete-plus.defaultProvider": "Subsequence" | "Symbol";
+
+    /**
+     * Don't auto-activate when any of these classes are present in the editor.
+     */
+    "autocomplete-plus.suppressActivationForEditorClasses": string[];
+
+    /**
+     * Completing a suggestion consumes text following the cursor matching the
+     * suffix of the chosen suggestion.
+     */
+    "autocomplete-plus.consumeSuffix": boolean;
+
+    /**
+     * Prefers runs of consecutive characters, acronyms and start of words.
+     */
+    "autocomplete-plus.useAlternateScoring": boolean;
+
+    /**
+     * Gives words near the cursor position a higher score than those far away.
+     */
+    "autocomplete-plus.useLocalityBonus": boolean;
+
+    /** Identifies non-latin alphabet characters as letters. */
+    "autocomplete-plus.enableExtendedUnicodeSupport": boolean;
+
+    /**
+     * Should similar suggestions be removed from the list? If so how to
+     * determine they are similar.
+     */
+    "autocomplete-plus.similarSuggestionRemoval": "none" | "textOrSnippet";
+  }
+}

package/autocomplete-plus/index.d.ts

@@ -0,0 +1,200 @@
+// Autocomplete Plus 2.x
+// https://web.pulsar-edit.dev/packages/autocomplete-plus
+
+/// <reference path="./config.d.ts" />
+
+import { Point, ScopeDescriptor, TextEditor } from "../index";
+
+/** The parameters passed into getSuggestions by Autocomplete+. */
+export interface SuggestionsRequestedEvent {
+  /** The current TextEditor. */
+  editor: TextEditor;
+
+  /** The position of the cursor. */
+  bufferPosition: Point;
+
+  /** The scope descriptor for the current cursor position. */
+  scopeDescriptor: ScopeDescriptor;
+
+  /**
+   * The prefix for the word immediately preceding the current cursor position.
+   */
+  prefix: string;
+
+  /** Whether the autocomplete request was initiated by the user. */
+  activatedManually: boolean;
+}
+
+/** The parameters passed into onDidInsertSuggestion by Autocomplete+. */
+export interface SuggestionInsertedEvent {
+  editor: TextEditor;
+  triggerPosition: Point;
+  suggestion: TextSuggestion | SnippetSuggestion;
+}
+
+/**
+ * An autocompletion suggestion for the user.
+ *
+ * Primary data type for the Atom Autocomplete+ service.
+ */
+export interface SuggestionBase {
+  /**
+   * A string that will show in the UI for this suggestion.
+   *
+   * When not set, `snippet || text` is displayed.
+   */
+  displayText?: string;
+
+  /**
+   * The text immediately preceding the cursor, which will be replaced by the
+   * text. If not provided, the prefix passed into getSuggestions will be used.
+   */
+  replacementPrefix?: string;
+
+  /**
+   *  The suggestion type. It will be converted into an icon shown against the
+   *  suggestion.
+   */
+  type?: string;
+
+  /** This is shown before the suggestion. Useful for return values. */
+  leftLabel?: string;
+
+  /**
+   * Use this instead of `leftLabel` if you want to use HTML for the left
+   * label.
+   */
+  leftLabelHTML?: string;
+
+  /**
+   * An indicator (e.g. function, variable) denoting the "kind" of suggestion
+   * this represents.
+   */
+  rightLabel?: string;
+
+  /**
+   * Use this instead of `rightLabel` if you want to use HTML for the right
+   * label.
+   */
+  rightLabelHTML?: string;
+
+  /**
+   * Class name for the suggestion in the suggestion list.
+   *
+   * Allows you to style your suggestion via CSS, if desired.
+   */
+  className?: string;
+
+  /**
+   * If you want complete control over the icon shown against the suggestion.
+   *
+   * e.g. `iconHTML: '<i class="icon-move-right"></i>'`
+   */
+  iconHTML?: string;
+
+  /**
+   * A doc-string summary or short description of the suggestion.
+   *
+   * When specified, it will be displayed at the bottom of the suggestions
+   * list.
+   */
+  description?: string;
+
+  /**
+   * A url to the documentation or more information about this suggestion.
+   *
+   * When specified, a "More.." link will be displayed in the description area.
+   */
+  descriptionMoreURL?: string;
+
+  /**
+   * Description with Markdown formatting.
+   *
+   * Takes precedence over plaintext description.
+   */
+  descriptionMarkdown?: string;
+}
+
+export interface TextSuggestion extends SuggestionBase {
+  /** The text which will be inserted into the editor, in place of the prefix. */
+  text: string;
+}
+
+export interface SnippetSuggestion extends SuggestionBase {
+  /**
+   *  A snippet string. This will allow users to tab through function arguments
+   *  or other options.
+   */
+  snippet: string;
+}
+
+export type AnySuggestion = TextSuggestion | SnippetSuggestion;
+export type Suggestion = AnySuggestion;
+export type Suggestions = AnySuggestion[];
+
+/** The interface that all Autocomplete+ providers must implement. */
+export interface AutocompleteProvider {
+  /**
+   * Defines the scope selector(s) (can be comma-separated) for which your
+   * provider should receive suggestion requests.
+   */
+  selector: string;
+
+  /**
+   * Defines the scope selector(s) (can be comma-separated) for which your
+   * provider should not be used.
+   */
+  disableForSelector?: string;
+
+  /**
+   * A number to indicate its priority to be included in a suggestions request.
+   *
+   * The default provider has an inclusion priority of 0. Higher priority
+   * providers can suppress lower priority providers with
+   * {@link excludeLowerPriority}.
+   */
+  inclusionPriority?: number;
+
+  /** Will not use lower priority providers when this provider is used. */
+  excludeLowerPriority?: boolean;
+
+  /**
+   * A number to determine the sort order of suggestions.
+   *
+   * The default provider has a suggestion priority of 1.
+   */
+  suggestionPriority?: number;
+
+  /**
+   * Whether to allow Autocomplete+ to filter and sort the suggestions you
+   * provide.
+   */
+  filterSuggestions?: boolean;
+
+  /**
+   * Called when a suggestion request has been dispatched by Autocomplete+ to
+   * your provider.
+   *
+   * Return an array of suggestions (if any) in the order you would like them
+   * displayed to the user. Returning a promise of an array of suggestions is
+   * also supported.
+   */
+  getSuggestions(params: SuggestionsRequestedEvent): Suggestions | Promise<Suggestions>;
+
+  /**
+   * Called when a suggestion is selected by the user for the purpose of
+   * loading more information about the suggestion.
+   *
+   * Return a promise of the new suggestion to replace it with or return `null`
+   * if no change is needed.
+   */
+  getSuggestionDetailsOnSelect?(suggestion: AnySuggestion): Promise<AnySuggestion | null> | AnySuggestion | null;
+
+  /**
+   * Called when a suggestion from your provider was inserted into the buffer.
+   */
+  onDidInsertSuggestion?(params: SuggestionInsertedEvent): void;
+
+  /** Called if your provider is being destroyed by Autocomplete+. */
+  dispose?(): void;
+}