@prairielearn/utils 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @prairielearn/utils
+
+## 2.0.0
+
+### Major Changes
+
+- 3eb682b: Introduce `@prairielearn/utils` package

package/README.md

@@ -0,0 +1,23 @@
+# `@prairielearn/utils`
+
+Various shared utilities.
+
+## Usage
+
+### `withResolvers()`
+
+A tiny utility for creating Promises with exposed `resolve` and `reject` methods, similar to [`Promise.withResolvers()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers).
+
+Once `Promise.withResolvers()` is widely supported in browsers, users of this package should switch to it.
+
+```ts
+import { withResolvers } from '@prairielearn/utils';
+
+const { promise, resolve, reject } = withResolvers<number>();
+
+setTimeout(() => resolve(42), 100);
+
+promise.then((value) => {
+  console.log(value); // 42
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * An object containing a promise and its resolve/reject methods.
+ */
+export interface PromiseWithResolvers<T> {
+    /** The promise instance. */
+    promise: Promise<T>;
+    /** Resolves the promise. */
+    resolve: (value: T | PromiseLike<T>) => void;
+    /** Rejects the promise. */
+    reject: (reason?: any) => void;
+}
+/**
+ * Returns an object with a promise and its resolve/reject methods exposed.
+ * This is similar to Node.js's util.withResolvers (Node 21+).
+ *
+ * @returns An object containing the promise, resolve, and reject.
+ */
+export declare function withResolvers<T>(): PromiseWithResolvers<T>;

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * Returns an object with a promise and its resolve/reject methods exposed.
+ * This is similar to Node.js's util.withResolvers (Node 21+).
+ *
+ * @returns An object containing the promise, resolve, and reject.
+ */
+export function withResolvers() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve: resolve, reject: reject };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,OAA4C,CAAC;IACjD,IAAI,MAA8B,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC1C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IACf,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAQ,EAAE,MAAM,EAAE,MAAO,EAAE,CAAC;AACzD,CAAC","sourcesContent":["/**\n * An object containing a promise and its resolve/reject methods.\n */\nexport interface PromiseWithResolvers<T> {\n  /** The promise instance. */\n  promise: Promise<T>;\n  /** Resolves the promise. */\n  resolve: (value: T | PromiseLike<T>) => void;\n  /** Rejects the promise. */\n  reject: (reason?: any) => void;\n}\n\n/**\n * Returns an object with a promise and its resolve/reject methods exposed.\n * This is similar to Node.js's util.withResolvers (Node 21+).\n *\n * @returns An object containing the promise, resolve, and reject.\n */\nexport function withResolvers<T>(): PromiseWithResolvers<T> {\n  let resolve: (value: T | PromiseLike<T>) => void;\n  let reject: (reason?: any) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve: resolve!, reject: reject! };\n}\n"]}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { withResolvers } from './index.js';
+describe('withResolvers', () => {
+    it('resolves with the correct value', async () => {
+        const { promise, resolve } = withResolvers();
+        setTimeout(() => resolve(123), 10);
+        await expect(promise).resolves.toBe(123);
+    });
+    it('rejects with the correct reason', async () => {
+        const { promise, reject } = withResolvers();
+        setTimeout(() => reject(new Error('fail')), 10);
+        await expect(promise).rejects.toThrow('fail');
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,aAAa,EAAU,CAAC;QACrD,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;QACnC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,EAAU,CAAC;QACpD,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { describe, expect, it } from 'vitest';\n\nimport { withResolvers } from './index.js';\n\ndescribe('withResolvers', () => {\n  it('resolves with the correct value', async () => {\n    const { promise, resolve } = withResolvers<number>();\n    setTimeout(() => resolve(123), 10);\n    await expect(promise).resolves.toBe(123);\n  });\n\n  it('rejects with the correct reason', async () => {\n    const { promise, reject } = withResolvers<number>();\n    setTimeout(() => reject(new Error('fail')), 10);\n    await expect(promise).rejects.toThrow('fail');\n  });\n});\n"]}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@prairielearn/utils",
+  "version": "2.0.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrairieLearn/PrairieLearn.git",
+    "directory": "packages/utils"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "test": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@prairielearn/tsconfig": "^0.0.0",
+    "@types/node": "^22.18.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { withResolvers } from './index.js';
+
+describe('withResolvers', () => {
+  it('resolves with the correct value', async () => {
+    const { promise, resolve } = withResolvers<number>();
+    setTimeout(() => resolve(123), 10);
+    await expect(promise).resolves.toBe(123);
+  });
+
+  it('rejects with the correct reason', async () => {
+    const { promise, reject } = withResolvers<number>();
+    setTimeout(() => reject(new Error('fail')), 10);
+    await expect(promise).rejects.toThrow('fail');
+  });
+});

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * An object containing a promise and its resolve/reject methods.
+ */
+export interface PromiseWithResolvers<T> {
+  /** The promise instance. */
+  promise: Promise<T>;
+  /** Resolves the promise. */
+  resolve: (value: T | PromiseLike<T>) => void;
+  /** Rejects the promise. */
+  reject: (reason?: any) => void;
+}
+
+/**
+ * Returns an object with a promise and its resolve/reject methods exposed.
+ * This is similar to Node.js's util.withResolvers (Node 21+).
+ *
+ * @returns An object containing the promise, resolve, and reject.
+ */
+export function withResolvers<T>(): PromiseWithResolvers<T> {
+  let resolve: (value: T | PromiseLike<T>) => void;
+  let reject: (reason?: any) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve: resolve!, reject: reject! };
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@prairielearn/tsconfig/tsconfig.package.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    coverage: {
+      reporter: ['html', 'text-summary', 'cobertura'],
+      all: true,
+      include: ['src/**'],
+    },
+  },
+});