isomorphic-git 1.33.3 → 1.34.1

package/README.md

@@ -392,7 +392,11 @@ Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds
     <td align="center"><a href="https://github.com/gnillev"><img src="https://avatars.githubusercontent.com/u/8965094?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Mathias Nisted Velling</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=gnillev" title="Code">💻</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=gnillev" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://github.com/acandoo"><img src="https://avatars.githubusercontent.com/u/117209328?v=4?s=60" width="60px;" alt=""/><br /><sub><b>acandoo</b></sub></a><br /><a href="#platform-acandoo" title="Packaging/porting to new platform">📦</a> <a href="#userTesting-acandoo" title="User Testing">📓</a></td>
     <td align="center"><a href="https://github.com/bekatan"><img src="https://avatars.githubusercontent.com/u/19550476?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Bekatan Satyev</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=bekatan" title="Code">💻</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=bekatan" title="Tests">⚠️</a></td>
+  </tr>
+  <tr>
     <td align="center"><a href="https://github.com/hemanthkini"><img src="https://avatars.githubusercontent.com/u/3934055?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Hemanth Kini</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=hemanthkini" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/anish3333"><img src="https://avatars.githubusercontent.com/u/128889867?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Anish Awasthi</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=anish3333" title="Code">💻</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=anish3333" title="Documentation">📖</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=anish3333" title="Tests">⚠️</a></td>
+    <td align="center"><a href="https://github.com/fetsorn"><img src="https://avatars.githubusercontent.com/u/12858105?v=4?s=60" width="60px;" alt=""/><br /><sub><b>fetsorn</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=fetsorn" title="Documentation">📖</a></td>
   </tr>
 </table>
 

package/browser-tests.json

@@ -1,8 +1,13 @@
 [
   "Chrome Headless 79.0.3945.0 (Linux x86_64)",
   "Firefox 143.0 (Linux x86_64)",
-  "Chrome 137.0.0.0 (Android 10)",
   "Mobile Safari 14.0 (iOS 14.0.1)",
-  "Edge 79.0.309.65 (Windows 10)",
-  "Safari 14.1 (Mac OS 10.15.7)"
+  "Safari 14.1 (Mac OS 10.15.7)",
+  "Chrome 139.0.0.0 (Android 10)",
+  "X Edge 79.0.309.65 (Windows 10)",
+  "X Edge 79.0.309.65 (Windows 10)",
+  "X Edge 79.0.309.65 (Windows 10)",
+  "X Edge 79.0.309.65 (Windows 10)",
+  "Chrome Headless 79.0.3945.0 (Linux x86_64)",
+  "Chrome 139.0.0.0 (Android 10)"
 ]

package/index.cjs

@@ -8067,8 +8067,8 @@ function filterCapabilities(server, client) {
 
 const pkg = {
   name: 'isomorphic-git',
-  version: '1.33.3',
-  agent: 'git/isomorphic-git@1.33.3',
+  version: '1.34.1',
+  agent: 'git/isomorphic-git@1.34.1',
 };
 
 class FIFO {
@@ -15013,8 +15013,7 @@ class GitStashManager {
       return []
     }
 
-    const reflogBuffer = await this.fs.read(this.refLogsStashPath);
-    const reflogString = reflogBuffer.toString();
+    const reflogString = await this.fs.read(this.refLogsStashPath, 'utf8');
 
     return GitRefStash.getStashReflogEntry(reflogString, parsed)
   }
@@ -15022,7 +15021,11 @@ class GitStashManager {
 
 // @ts-check
 
-async function _stashPush({ fs, dir, gitdir, message = '' }) {
+/**
+ * Common logic for creating a stash commit
+ * @private
+ */
+async function _createStashCommit({ fs, dir, gitdir, message = '' }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
   await stashMgr.getAuthor(); // ensure there is an author
@@ -15057,7 +15060,7 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     // create a commit from the index tree, which has one parent, the current branch HEAD
     const stashCommitOne = await stashMgr.writeStashCommit({
       message: `stash-Index: WIP on ${branch} - ${new Date().toISOString()}`,
-      tree: indexTree, // stashCommitTree
+      tree: indexTree,
       parent: stashCommitParents,
     });
     stashCommitParents.push(stashCommitOne);
@@ -15098,6 +15101,17 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     parent: stashCommitParents,
   });
 
+  return { stashCommit, stashMsg, branch, stashMgr }
+}
+
+async function _stashPush({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit, stashMsg, branch, stashMgr } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
   // next, write this commit into .git/refs/stash:
   await stashMgr.writeStashRef(stashCommit);
 
@@ -15120,6 +15134,18 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
   return stashCommit
 }
 
+async function _stashCreate({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
+  // Return the stash commit hash without modifying refs or working directory
+  return stashCommit
+}
+
 async function _stashApply({ fs, dir, gitdir, refIdx = 0 }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
@@ -15223,21 +15249,22 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
 // @ts-check
 
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -15272,6 +15299,10 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 
 async function stash({
@@ -15294,6 +15325,7 @@ async function stash({
     list: _stashList,
     clear: _stashClear,
     pop: _stashPop,
+    create: _stashCreate,
   };
 
   const opsNeedRefIdx = ['apply', 'drop', 'pop'];

package/index.d.cts

@@ -3033,21 +3033,22 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
     append?: boolean | undefined;
 }): Promise<void>;
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -3082,12 +3083,16 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 export function stash({ fs, dir, gitdir, op, message, refIdx, }: {
     fs: FsClient;
     dir?: string | undefined;
     gitdir?: string | undefined;
-    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | undefined;
+    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | "create" | undefined;
     message?: string | undefined;
     refIdx?: number | undefined;
 }): Promise<string | void>;

package/index.d.ts

@@ -3032,21 +3032,22 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
     append?: boolean | undefined;
 }): Promise<void>;
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -3081,12 +3082,16 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 export function stash({ fs, dir, gitdir, op, message, refIdx, }: {
     fs: FsClient;
     dir?: string | undefined;
     gitdir?: string | undefined;
-    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | undefined;
+    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | "create" | undefined;
     message?: string | undefined;
     refIdx?: number | undefined;
 }): Promise<string | void>;

package/index.js

@@ -8061,8 +8061,8 @@ function filterCapabilities(server, client) {
 
 const pkg = {
   name: 'isomorphic-git',
-  version: '1.33.3',
-  agent: 'git/isomorphic-git@1.33.3',
+  version: '1.34.1',
+  agent: 'git/isomorphic-git@1.34.1',
 };
 
 class FIFO {
@@ -15007,8 +15007,7 @@ class GitStashManager {
       return []
     }
 
-    const reflogBuffer = await this.fs.read(this.refLogsStashPath);
-    const reflogString = reflogBuffer.toString();
+    const reflogString = await this.fs.read(this.refLogsStashPath, 'utf8');
 
     return GitRefStash.getStashReflogEntry(reflogString, parsed)
   }
@@ -15016,7 +15015,11 @@ class GitStashManager {
 
 // @ts-check
 
-async function _stashPush({ fs, dir, gitdir, message = '' }) {
+/**
+ * Common logic for creating a stash commit
+ * @private
+ */
+async function _createStashCommit({ fs, dir, gitdir, message = '' }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
   await stashMgr.getAuthor(); // ensure there is an author
@@ -15051,7 +15054,7 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     // create a commit from the index tree, which has one parent, the current branch HEAD
     const stashCommitOne = await stashMgr.writeStashCommit({
       message: `stash-Index: WIP on ${branch} - ${new Date().toISOString()}`,
-      tree: indexTree, // stashCommitTree
+      tree: indexTree,
       parent: stashCommitParents,
     });
     stashCommitParents.push(stashCommitOne);
@@ -15092,6 +15095,17 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     parent: stashCommitParents,
   });
 
+  return { stashCommit, stashMsg, branch, stashMgr }
+}
+
+async function _stashPush({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit, stashMsg, branch, stashMgr } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
   // next, write this commit into .git/refs/stash:
   await stashMgr.writeStashRef(stashCommit);
 
@@ -15114,6 +15128,18 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
   return stashCommit
 }
 
+async function _stashCreate({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
+  // Return the stash commit hash without modifying refs or working directory
+  return stashCommit
+}
+
 async function _stashApply({ fs, dir, gitdir, refIdx = 0 }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
@@ -15217,21 +15243,22 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
 // @ts-check
 
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -15266,6 +15293,10 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 
 async function stash({
@@ -15288,6 +15319,7 @@ async function stash({
     list: _stashList,
     clear: _stashClear,
     pop: _stashPop,
+    create: _stashCreate,
   };
 
   const opsNeedRefIdx = ['apply', 'drop', 'pop'];

package/index.umd.min.d.ts

@@ -3032,21 +3032,22 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
     append?: boolean | undefined;
 }): Promise<void>;
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -3081,12 +3082,16 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 export function stash({ fs, dir, gitdir, op, message, refIdx, }: {
     fs: FsClient;
     dir?: string | undefined;
     gitdir?: string | undefined;
-    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | undefined;
+    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | "create" | undefined;
     message?: string | undefined;
     refIdx?: number | undefined;
 }): Promise<string | void>;