@tomjs/vscode/dist/index.d.ts

Some utilities to simplify the development of VSCode Extensions

import * as vscode from 'vscode';
import { ConfigurationTarget, ExtensionContext, WorkspaceFolder } from 'vscode';

declare class Configuration<T> {
  private _defaultValues;
  private _values;
  private identifier;
  constructor(identifier: string, defaultValues?: T);
  configuration(): vscode.WorkspaceConfiguration;
  /**
   * Return a value from this configuration.
   * @param section — Configuration name, supports dotted names.
   * @param defaultValue — A value should be returned when no value could be found, is undefined.
   * @returns — The value section denotes or the default.
   */
  get<T>(section: string): T | undefined;
  get<T>(section: string, defaultValue: T): T | undefined;
  /**
   * Get all Configuration values.
   */
  values(): T;
  /**
   * Update a configuration value. The updated configuration values are persisted.
   * @param section Configuration name, supports dotted names.
   * @param value  The new value.
   * @param target The {@link ConfigurationTarget configuration target} or a boolean value. Defaults to `true`
   *	- If `true` updates {@link ConfigurationTarget.Global Global settings}.
   *	- If `false` updates {@link ConfigurationTarget.Workspace Workspace settings}.
   *	- If `undefined` or `null` updates to {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings} if configuration is resource specific,
   * 	otherwise to {@link ConfigurationTarget.Workspace Workspace settings}.
   */
  update(section: string, value: any, target?: ConfigurationTarget | boolean | null): Promise<void>;
  /**
   * Update configuration values. The updated configuration values are persisted.
   * @param values Configuration names and values, supports dotted names.
   * @param target The {@link ConfigurationTarget configuration target} or a boolean value. Defaults to `true`
   *	- If `true` updates {@link ConfigurationTarget.Global Global settings}.
   *	- If `false` updates {@link ConfigurationTarget.Workspace Workspace settings}.
   *	- If `undefined` or `null` updates to {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings} if configuration is resource specific,
   * 	otherwise to {@link ConfigurationTarget.Workspace Workspace settings}.
   */
  update(values: T, target?: ConfigurationTarget | boolean | null): Promise<void>;
}

/**
 * Whether the current version is insider.
 */
declare const isInsider: boolean;

declare function setExtensionContext(ctx: ExtensionContext): void;
/**
 * Get current extension context
 */
declare function getExtensionContext(): ExtensionContext;
/**
 * Get current extension context
 */
declare function getCtx(): ExtensionContext;

/**
 * The extension is running from an --extensionDevelopmentPath provided when launching the editor.
 */
declare function isUnderDevelopment(): boolean;
/**
 * The extension is installed normally (for example, from the marketplace or VSIX) in the editor.
 */
declare function isUnderProduction(): boolean;

declare function loadI18n(extensionPath: string, language?: string): any;
/**
 * Read i18n messages from package.nls.json
 */
interface NlsI18n {
  /**
   * Loads the nls messages for the given messages.
   * @param messages - The messages to use.
   */
  use(messages: Record<string, string>): void;
  /**
   * Loads the nls messages for the given path and language.
   * @param extensionPath - The extension path.
   * @param language - The language to load. Defaults to {@link env.language}.
   */
  use(extensionPath: string, language?: string): void;
  /**
   * Marks a string for localization. If a localized bundle is available for the language specified by
   * {@link env.language} and the bundle has a localized value for this message, then that localized
   * value will be returned (with injected {@link args} values for any templated values).
   *
   * @param message - The message to localize. Supports index templating where strings like `{0}` and `{1}` are
   * replaced by the item at that index in the {@link args} array.
   * @param args - The arguments to be used in the localized string. The index of the argument is used to
   * match the template placeholder in the localized string.
   * @returns localized string with injected arguments.
   *
   * @example
   * i18n.t('Hello {0}!', 'World');
   */
  t(message: string, ...args: Array<string | number | boolean>): string;
  /**
   * Marks a string for localization. If a localized bundle is available for the language specified by
   * {@link env.language} and the bundle has a localized value for this message, then that localized
   * value will be returned (with injected {@link args} values for any templated values).
   *
   * @param message The message to localize. Supports named templating where strings like `{foo}` and `{bar}` are
   * replaced by the value in the Record for that key (foo, bar, etc).
   * @param args The arguments to be used in the localized string. The name of the key in the record is used to
   * match the template placeholder in the localized string.
   * @returns localized string with injected arguments.
   *
   * @example
   * i18n.t('Hello {name}!', { name: 'World' });
   */
  t(message: string, args: Record<string, any>): string;
  t(
    ...params:
      | [message: string, ...args: Array<string | number | boolean>]
      | [message: string, args: Record<string, any>]
  ): string;
}
/**
 * Read i18n messages from package.nls.json
 */
declare class I18n implements NlsI18n {
  private messages;
  /**
   * Loads the nls messages for the given messages or path.
   * @param messages - The i18n messages or extension path.
   * - If a string is passed, it will be used as the extension path.
   * - If an object is passed, it will be used as the messages.
   * - If nothing is passed, you can use {@link use} to load the messages later.
   * @param language - The language to load. Defaults to {@link env.language}.
   */
  constructor(messages?: Record<string, string> | string, language?: string);
  /**
   * Loads the nls messages for the given messages.
   * @param messages - The messages to use.
   */
  use(messages: Record<string, string>): void;
  /**
   * Loads the nls messages for the given path and language.
   * @param extensionPath - The extension path.
   * @param language - The language to load. Defaults to {@link env.language}.
   */
  use(extensionPath: string, language?: string): void;
  t(
    ...params:
      | [message: string, ...args: Array<string | number | boolean>]
      | [message: string, args: Record<string, any>]
  ): string;
}
/**
 * The i18n instance.
 */
declare const i18n: NlsI18n;

/**
 * Get user data path
 *
 * * windows: %APPDATA%\\Code\\User
 * * mac: ~/Library/Application Support/Code/User
 * * linux: ~/.config/Code/User
 */
declare function getUserDataPath(): string;
/**
 * Get .vscode path
 *
 * * windows: %USERPROFILE%\\.vscode
 * * mac: ~/.vscode
 * * linux: ~/.vscode
 */
declare function getDotVSCodePath(): string;

/**
 * Get the active workspace folder
 */
declare function getActiveWorkspaceFolder(): WorkspaceFolder | undefined;
/**
 * Get the active workspace folder uri
 */
declare function getActiveWorkspaceFolderUri(): vscode.Uri | undefined;
/**
 * Get the active workspace folder path
 */
declare function getActiveWorkspaceFolderPath(): string | undefined;
/**
 * Get all workspace folders
 */
declare function getAllWorkspaceFolders(): (WorkspaceFolder & {
  active?: boolean | undefined;
})[];

/**
 * Initialize Extension Utils
 */
declare function initExtension(ctx: ExtensionContext): void;
declare const _default: {
  /**
   * Initialize Extension Utils
   */
  init: typeof initExtension;
};

export {
  Configuration,
  I18n,
  type NlsI18n,
  _default as default,
  getActiveWorkspaceFolder,
  getActiveWorkspaceFolderPath,
  getActiveWorkspaceFolderUri,
  getAllWorkspaceFolders,
  getCtx,
  getDotVSCodePath,
  getExtensionContext,
  getUserDataPath,
  i18n,
  initExtension,
  isInsider,
  isUnderDevelopment,
  isUnderProduction,
  loadI18n,
  setExtensionContext,
};