You're Invited:Meet the Socket Team at RSAC and BSidesSF 2026, March 23–26.RSVP →
Socket
Book a DemoSign in
Socket
Book a DemoSign in

@withfig/autocomplete-types

Package Overview
Dependencies
Maintainers
7
Versions
31
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@withfig/autocomplete-types - npm Package Compare versions

Comparing version
1.28.0
 to
1.29.0
+88
-121
index.d.ts

@@ -27,2 +27,3 @@ /* eslint-disable @typescript-eslint/ban-types */

* `ls` used ["filepaths", "folders"]. Why both? Because if I `ls` a directory, we want to enable a user to autoexecute on this directory. If we just did "filepaths" they couldn't autoexecute.
*
*/

@@ -50,2 +51,3 @@ type Template = TemplateStrings | TemplateStrings[];

/**
*
* The SpecLocation object defines well... the location of the completion spec we want to load.

@@ -93,3 +95,3 @@ * Specs can be "global" (ie hosted by Fig's cloud) or "local" (ie stored on your local machine)

token: string,
executeShellCommand: ExecuteShellCommandFunction
executeCommand: ExecuteCommandFunction
) => Promise<SpecLocation | SpecLocation[] | Subcommand>);

@@ -124,3 +126,3 @@

*
* @param executeShellCommand -an async function that allows you to execute a shell command on the user's system and get the output as a string.
* @param executeCommand -an async function that allows you to execute a shell command on the user's system and get the output as a string.
* @returns The version of a CLI tool

@@ -133,4 +135,5 @@ *

* `v26`
*
*/
type GetVersionCommand = (executeShellCommand: ExecuteShellCommandFunction) => Promise<string>;
type GetVersionCommand = (executeCommand: ExecuteCommandFunction) => Promise<string>;

@@ -168,2 +171,3 @@ /**

type Modify<T, R> = Omit<T, keyof R> & R;
/**

@@ -237,79 +241,44 @@ * A `string` OR a `function` which can have a `T` argument and a `R` result.

/**
* An async function to execute a shell command
* @param commandToExecute - The shell command you want to execute
* @param cwd - The directory in which to execute the command
* @returns The output of the shell command as a string
*
* @remarks
* The `cwd` parameter will add a `cd [cwd] &&` before the command itself.
* @example
* `ExecuteShellCommandFunction("echo hello world")` will return `hello world`
*/
type ExecuteShellCommandFunction = (commandToExecute: string, cwd?: string) => Promise<string>;
/**
* @excluded
*/
type ExecFunctionOptions = (
| {
/**
* The command to execute, this will be executed in bash like a normal shell command.
* @example
* `echo hello world`
* @example
* `ls`
*/
command: string;
}
| {
/**
* This will execute the command without a shell, so you can use this to execute a binary.
* @example
* ["ls", "-a"]
*/
args: string[];
}
) & {
type ExecuteCommandInput = {
/**
* The directory in which to execute the command, if not specified, the current working directory will be used.
* The command to execute
*/
cwd?: string;
command: string;
/**
* Whether to clear the environment variables or not before executing the command.
* @default false
* The arguments to the command to be run
*/
clearEnv?: boolean;
args: string[];
/**
* The environment variables to set before executing the command.
* @example
* { PATH: "/usr/bin", HELLO: "world", FOO: null }
* The directory to run the command in
*/
env?: Record<string, string | null>;
cwd?: string;
/**
* The environment variables to set when executing the command, `undefined` will unset the variable if it set
*/
env?: Record<string, string | undefined>;
};
/**
* The result of the `ExecuteShellCommandFunction`
*
* @excluded
* The output of running a command
*/
type ExecFunctionResult = {
type ExecuteCommandOutput = {
/**
* The output of the command on stdout.
* The stdout (1) of running a command
*/
stdout: string;
/**
* The output of the command on stderr.
* The stderr (2) of running a command
*/
stderr: string;
/**
* The exit code of the command.
* The exit status of running a command
*/
exitCode: number;
status: number;
};
/**
* @excluded
* An async function to execute a command
* @returns The output of the command
*/
type ExecFunction = (options: ExecFunctionOptions) => Promise<ExecFunctionResult>;
type ExecuteCommandFunction = (args: ExecuteCommandInput) => Promise<ExecuteCommandOutput>;

@@ -436,2 +405,3 @@ type CacheMaxAge = {

* `fig://icon?type=file`
*
*/

@@ -486,2 +456,3 @@ icon?: string;

/**
*
* Specifies whether a suggestion is deprecated.

@@ -511,3 +482,2 @@ * @remarks

*
* @excluded
* @ignore

@@ -534,2 +504,3 @@ */

* If a user types git `c`, any Suggestion objects with a name prop that has a value starting with "c" will match.
*
*/

@@ -563,2 +534,3 @@ name?: SingleOrArray<string>;

*
*
* @example

@@ -599,2 +571,3 @@ * For `git checkout`, the subcommand `checkout` would have `name: "checkout"`

* An array of `Arg` objects representing the various parameters or "arguments" that can be passed to this subcommand.
*
*/

@@ -637,2 +610,3 @@ args?: SingleOrArray<Arg>;

* You can use this field to suggest common workflows.
*
*/

@@ -644,3 +618,3 @@ additionalSuggestions?: (string | Suggestion)[];

* @param tokens - a tokenized array of the text the user has typed in the shell.
* @param executeShellCommand - an async function that can execute a shell command on behalf of the user. The output is a string.
* @param executeCommand - an async function that can execute a shell command on behalf of the user. The output is a string.
* @returns A `SpecLocation` object or an array of `SpecLocation` objects.

@@ -679,3 +653,3 @@ *

* @param tokens - a tokenized array of the text the user has typed in the shell.
* @param executeShellCommand - an async function that can execute a shell command on behalf of the user. The output is a string.
* @param executeCommand - an async function that can execute a shell command on behalf of the user. The output is a string.
* @returns a `Fig.Spec` object

@@ -686,5 +660,5 @@ *

* ```typescript
* generateSpec: async (tokens, executeShellCommand) => {
* generateSpec: async (tokens, executeCommand) => {
* // Load the contents of manage.py
* const managePyContents = await executeShellCommand("cat manage.py");
* const managePyContents = await executeCommand("cat manage.py");
* // Heuristic to determine if project uses django

@@ -700,6 +674,3 @@ * if (managePyContents.contains("django")) {

*/
generateSpec?: (
tokens: string[],
executeShellCommand: ExecuteShellCommandFunction
) => Promise<Spec>;
generateSpec?: (tokens: string[], executeCommand: ExecuteCommandFunction) => Promise<Spec>;

@@ -749,2 +720,3 @@ /**

*
*
* @example

@@ -773,2 +745,3 @@ * For `git commit -m` in the, message option nested beneath `commit` would have `name: ["-m", "--message"]`

/**
*
* Signals whether an option is persistent, meaning that it will still be available

@@ -788,2 +761,3 @@ * as an option for all child subcommands.

* as a valid as we are passing the `--help` option to all `git` subcommands.
*
*/

@@ -797,5 +771,7 @@ isPersistent?: boolean;

* The `-m` option of `git commit` is required
*
*/
isRequired?: boolean;
/**
*
* Signals whether an equals sign is required to pass an argument to an option (e.g. `git commit --message="msg"`)

@@ -808,5 +784,7 @@ * @defaultValue false (does NOT require an equal)

* @deprecated use `requiresSeparator` instead
*
*/
requiresEquals?: boolean;
/**
*
* Signals whether one of the separators specified in parserDirectives is required to pass an argument to an option (e.g. `git commit --message[separator]"msg"`)

@@ -824,2 +802,3 @@ * If set to true this will automatically insert an equal after the option name.

/**
*
* Signals whether an option can be passed multiple times.

@@ -856,5 +835,7 @@ *

* and will treat this as an argument to `ssh`.
*
*/
isRepeatable?: boolean | number;
/**
*
* Signals whether an option is mutually exclusive with other options (ie if the user has this option, Fig should not show the options specified).

@@ -869,5 +850,8 @@ * @defaultValue false

* If we were defining the exclusive prop of the "-a" option, then we would have `exclusive: ["--interactive", "--patch"]`
*
*/
exclusiveOn?: string[];
/**
*
*
* Signals whether an option depends on other options (ie if the user has this option, Fig should only show these options until they are all inserted).

@@ -883,2 +867,3 @@ *

* In this case, `--extension` dependsOn `--project`
*
*/

@@ -951,5 +936,7 @@ dependsOn?: string[];

* `ls` used ["filepaths", "folders"]. Why both? Because if I `ls` a directory, we want to enable a user to autoexecute on this directory. If we just did "filepaths" they couldn't autoexecute.
*
*/
template?: Template;
/**
*
* Generators let you dynamically generate suggestions for arguments by running shell commands on a user's device.

@@ -1015,2 +1002,3 @@ *

*
*
* @defaultValue true

@@ -1036,2 +1024,3 @@ *

* variadic arguments haven't started yet
*
*/

@@ -1082,9 +1071,4 @@ optionsCanBreakVariadicArg?: boolean;

* This will debounce every keystroke event for this particular arg.
*
* If `true` the debounce time will be 200ms.
*
* If a number, the debounce time will be that number of milliseconds.
*
* @remarks
* If set and there are no keystroke events after the period of time, Fig will execute all the generators in this arg and return the suggestions.
* If there are no keystroke events after 100ms, Fig will execute all the generators in this arg and return the suggestions.
*

@@ -1094,3 +1078,3 @@ * @example

*/
debounce?: boolean | number;
debounce?: boolean;
/**

@@ -1101,2 +1085,3 @@ * The default value for an optional argument.

* Note: This is currently not used anywhere in Fig's autocomplete popup, but will be soon.
*
*/

@@ -1111,2 +1096,3 @@ default?: string;

* 2. `isScript` (See [Arg Object](https://fig.io/docs/reference/arg#isscript))
*
*/

@@ -1122,3 +1108,3 @@ loadSpec?: LoadSpec;

* @param token - The token that the user has just typed that is an alias for something else
* @param executeShellCommand -an async function that allows you to execute a shell command on the user's system and get the output as a string.
* @param executeCommand -an async function that allows you to execute a shell command on the user's system and get the output as a string.
* @returns The expansion of the alias that Fig's bash parser will reparse as if it were typed out in full, rather than the alias.

@@ -1138,3 +1124,3 @@ *

parserDirectives?: {
alias?: string | ((token: string, exec: ExecuteShellCommandFunction) => Promise<string>);
alias?: string | ((token: string, exec: ExecuteCommandFunction) => Promise<string>);
};

@@ -1145,2 +1131,3 @@ }

* The generator object is used to generate suggestions for an arg object. To do this, it runs a defined shell command on the user's device, gets the output, and returns a list of Suggestion objects.
*
*/

@@ -1162,5 +1149,7 @@ interface Generator {

* `ls` uses ["filepaths", "folders"]. Why both? Because if I `ls` a directory, we want to enable a user to autoexecute on this directory. If we just did "filepaths" they couldn't autoexecute.
*
*/
template?: Template;
/**
*
* A function to filter and modify suggestions returned by a template

@@ -1176,13 +1165,19 @@ *

/**
* The script / shell command you wish to run on the user's device at their shell session's current working directory.
*
* The command you wish to run on the user's device at their shell session's current working directory.
*
* @remarks
* You can either specify
* 1. a string to be executed (like `ls` or `git branch`)
* 2. a function to generate the string to be executed. The function takes in an array of tokens of the user input and should output a string. You use a function when the script you run is dependent upon one of the tokens the user has already input (for instance an app name, a Kubernetes token etc.)
* After executing the script, the output will be passed to one of `splitOn` or `postProcess` for further processing to produce suggestion objects.
* 1. a command and args to be executed (like `["ls"]` or `["git", "branch"]`)
* 2. a function to generate the command and args to be executed. The function takes in an array of tokens of the user input and should output a array of string (command and args). You use a function when the script you run is dependent upon one of the tokens the user has already input (for instance an app name, a Kubernetes token etc.)
* After executing the script, the stdout output will be passed to one of `splitOn` or `postProcess` for further processing to produce suggestion objects.
*
* @example
* `git checkout <branch>` takes one argument which is a git branch. Its arg object has a generator with a `script: "git branch"`. The output of this shell command is then passed into the postProcess function to generate the final suggestions.
* `git checkout <branch>` takes one argument which is a git branch. Its arg object has a generator with a `script: ["git", "branch"]"`. The stdout output of this shell command is then passed into the postProcess function to generate the final suggestions.
*/
script?: StringOrFunction<string[], string>;
script?:
| string[]
| Function<string[], string[]>
| ExecuteCommandInput
| Function<string[], ExecuteCommandInput>;
/**

@@ -1194,2 +1189,3 @@ * Set the execution timeout of the command specified in the `script` prop.

/**
*
* Process the string output from the `script` prop and return a list of suggestions

@@ -1200,2 +1196,3 @@ *

* @returns An array of `Suggestion` objects.
*
*/

@@ -1214,2 +1211,3 @@ postProcess?: (out: string, tokens: string[]) => Suggestion[];

/**
*
* A function run on every keystroke that determines whether Fig should invalidate its cached list of suggestions and instead regenerate its list of suggestions.

@@ -1234,2 +1232,3 @@ *

*
*
* @param newToken - The new token that was just typed by the user e.g. "desktop/""

@@ -1272,2 +1271,3 @@ * @param oldToken - The old token that was there before e.g. "desktop"

* if the user types cd `~/desktop/a`, the list of suggestions will be all the folders on the user's desktop. We want to filter over these folders with the query term `"a"` not `~/desktop/a`
*
*/

@@ -1282,3 +1282,3 @@ getQueryTerm?: StringOrFunction<string, string>;

* @param tokens - a tokenized array of what the user has typed
* @param executeShellCommand - an async function that allows you to execute a shell command on the user's system and get the output as a string.
* @param executeCommand - an async function that allows you to execute a shell command on the user's system and get the output as a string.
* @param shellContext - an object containing a user's currentWorkingDirectory, currentProcess, and if relevant, the sshPrefix string that can be used if the user is in an SSH session.

@@ -1297,4 +1297,4 @@ *

* const generator: Fig.Generator = {
* custom: async (tokens, executeShellCommand) => {
* const out = await executeShellCommand("ls");
* custom: async (tokens, executeCommand) => {
* const out = await executeCommand("ls");
* return out.split("\n").map((elm) => ({ name: elm }));

@@ -1307,41 +1307,7 @@ * },

tokens: string[],
executeShellCommand: ExecuteShellCommandFunction,
executeCommand: ExecuteCommandFunction,
generatorContext: GeneratorContext
) => Promise<Suggestion[]>;
/**
* Not yet supported, early work on new custom generator API
* @internal
* @excluded
*/
func?: (options: {
tokens: string[];
exec: ExecFunction;
executeShellCommand: ExecuteShellCommandFunction;
shellContext: ShellContext;
}) => Promise<Suggestion[]>;
/**
* Not yet supported, early work on new custom generator API
* @excluded
*/
stream?: (options: {
tokens: string[];
exec: ExecFunction;
executeShellCommand: ExecuteShellCommandFunction;
shellContext: ShellContext;
}) => AsyncGenerator<
(Suggestion & {
/**
* If you yield a suggestion with an id, it will upsert the suggestion with that id
*/
id?: string;
/**
* If marked as incomplete, Fig will show a loading indicator while the suggestion is being generated and it will not be able to be used
*/
incomplete?: boolean;
})[]
>;
/**
*
* Cache the response of generators for a specific period time and optionally by directory the commands were executed in.

@@ -1358,2 +1324,3 @@ *

* The kubernetes spec makes use of this.
*
*/

@@ -1360,0 +1327,0 @@ cache?: Cache;

+2
-1
package.json
{
"name": "@withfig/autocomplete-types",
"description": "Typings for fig autocomplete specs and other tools",
"version": "1.28.0",
"version": "1.29.0",
"author": "The Fig Team",

@@ -20,2 +20,3 @@ "types": "index.d.ts",

"@microsoft/tsdoc": "^0.14.1",
"@types/node": "^20.8.10",
"cspell": "^6.0.0",

@@ -22,0 +23,0 @@ "picocolors": "^1.0.0",