@ribbon-studios/js-utils 1.1.1

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+### 🤖 Contributing to Utils 💗
+
+See an [issue](/issues) or need that you're able to fulfill?
+Then this is the perfect place for you!
+
+## Prerequisites
+
+- NodeJS 18
+
+## Setting Up Locally
+
+- Install the Dependencies
+
+```bash
+bun install
+```
+
+## Run the Tests~
+
+```bash
+bun run test
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rainbow Cafe
+
+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,113 @@
+[![NPM Version][npm-version-image]][npm-url]
+[![NPM Downloads][npm-downloads-image]][npm-url]
+[![Coveralls][coveralls-image]][coveralls-url]
+
+[![CI Build][github-actions-image]][github-actions-url]
+[![Maintainability][maintainability-image]][maintainability-url]
+[![Semantic Release][semantic-release-image]][semantic-release-url]
+[![Code Style: Prettier][code-style-image]][code-style-url]
+
+</div>
+
+# JS Utils 🔧
+
+Collection of generic javascript utilities curated by the Rainbow Cafe~
+
+- [Promises](#promises)
+  - [`delay`](#delay)
+    - [`delay.fallback`](#delayfallback)
+  - [`assert`](#assert)
+    - [`assert.defined`](#assertdefined)
+  - [`never`](#never)
+
+## Promises
+
+### `delay`
+
+Creates a delayed promise for the given amount of seconds and given promises.
+This can be useful for allowing spinners / loading skeletons to exist for a bit rather then quickly popping in and out.
+
+```tsx
+import { delay } from '@ribbon-studios/js-utils';
+
+const promise = delay(); // Returns a promise with the preset delay
+const promise = delay(1000); // Returns a promise with the given delay
+const promise = delay(Promise.resolve('hello')); // Returns the original promise with the preset delay
+const promise = delay(Promise.resolve('hello'), 1000); // Returns the original promise with the given delay
+```
+
+### `delay.fallback`
+
+This overrides the default delay value
+
+```tsx
+import { delay } from '@ribbon-studios/js-utils';
+
+const promise = delay(); // Returns a promise with a delay of 500ms
+delay.fallback(100);
+const promise = delay(); // Returns a promise with a delay of 100ms
+```
+
+### `assert`
+
+On its own assert isn't overly useful just because of how type assertion works.
+
+```tsx
+import { assert } from '@ribbon-studios/js-utils';
+
+export async function example() {
+  const promise: Promise<string | undefined> = Promise.resolve('hello');
+  // Run an assertion on the promises response
+  const assertedPromise: Promise<string | undefined> = assert(promise, (value) => typeof value !== 'undefined');
+  // Unfortunately our response is still considered undefined because we can't forward the assertion
+}
+```
+
+### `assert.defined`
+
+Ensures the promise result is defined.
+
+```tsx
+import { assert } from '@ribbon-studios/js-utils';
+
+export async function example() {
+  const promise: Promise<string | undefined> = Promise.resolve('hello');
+
+  // Run an assertion on the promises response
+  const assertedPromise: Promise<string> = assert.defined(promise);
+  // Our promise is no longer considered undefined!
+
+  // You can also pass a message to throw!
+  const assertedPromise: Promise<string> = assert.defined(promise, 'Expected our thing to exist!');
+}
+```
+
+### `never`
+
+Creates a promise that never resolves.
+Primary use-case for this is testing loading states.
+
+In the event a promise is passed it will log a warning in the console as a reminder not to leave it in.
+
+```tsx
+import { never } from '@ribbon-studios/js-utils';
+
+const promise = never(); // Returns a promise that never resolves
+const promise = never(Promise.resolve('hello')); // Returns a promise that never resolves
+```
+
+[_**Want to Contribute?**_](/CONTRIBUTING.md)
+
+[npm-version-image]: https://img.shields.io/npm/v/@ribbon-studios/js-utils.svg
+[npm-downloads-image]: https://img.shields.io/npm/dm/@ribbon-studios/js-utils.svg
+[npm-url]: https://npmjs.org/package/@ribbon-studios/js-utils
+[github-actions-image]: https://img.shields.io/github/actions/workflow/status/ribbon-studios/js-utils/ci.yml?event=push
+[github-actions-url]: https://github.com/ribbon-studios/js-utils/actions/workflows/ci.yml?query=branch%3Amain
+[coveralls-image]: https://img.shields.io/coveralls/ribbon-studios/js-utils.svg
+[coveralls-url]: https://coveralls.io/github/ribbon-studios/js-utils?branch=main
+[code-style-image]: https://img.shields.io/badge/code%20style-prettier-ff69b4.svg
+[code-style-url]: https://prettier.io
+[maintainability-image]: https://img.shields.io/codeclimate/maintainability/ribbon-studios/refreshly
+[maintainability-url]: https://codeclimate.com/github/ribbon-studios/refreshly/maintainability
+[semantic-release-url]: https://github.com/semantic-release/semantic-release
+[semantic-release-image]: https://img.shields.io/badge/%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079

package/dist/index.cjs

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+async function assert(p, predicate, message) {
+  const value = await p;
+  if (predicate(value))
+    return value;
+  throw new Error(message ?? "Value does not satisfy predicate");
+}
+((assert2) => {
+  async function defined(p, message) {
+    return assert2(p, (v) => v !== void 0 && v !== null, message);
+  }
+  assert2.defined = defined;
+})(assert || (assert = {}));
+let fallbackDelay = 500;
+async function delay(promise, ms) {
+  if (typeof promise === "number") {
+    return await new Promise((resolve) => setTimeout(resolve, promise));
+  }
+  const [result] = await Promise.all([promise, new Promise((resolve) => setTimeout(resolve, ms ?? fallbackDelay))]);
+  return result;
+}
+((delay2) => {
+  function fallback(delay3) {
+    fallbackDelay = delay3;
+  }
+  delay2.fallback = fallback;
+})(delay || (delay = {}));
+async function never(p) {
+  if (p)
+    console.warn(`Promise is being called via "never", please ensure this doesn't get deployed!`, p);
+  return new Promise(() => {
+  });
+}
+exports.assert = assert;
+exports.delay = delay;
+exports.never = never;

package/dist/index.d.cts

@@ -0,0 +1 @@
+export * from './promises';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './promises';

package/dist/index.js

@@ -0,0 +1,37 @@
+async function assert(p, predicate, message) {
+  const value = await p;
+  if (predicate(value))
+    return value;
+  throw new Error(message ?? "Value does not satisfy predicate");
+}
+((assert2) => {
+  async function defined(p, message) {
+    return assert2(p, (v) => v !== void 0 && v !== null, message);
+  }
+  assert2.defined = defined;
+})(assert || (assert = {}));
+let fallbackDelay = 500;
+async function delay(promise, ms) {
+  if (typeof promise === "number") {
+    return await new Promise((resolve) => setTimeout(resolve, promise));
+  }
+  const [result] = await Promise.all([promise, new Promise((resolve) => setTimeout(resolve, ms ?? fallbackDelay))]);
+  return result;
+}
+((delay2) => {
+  function fallback(delay3) {
+    fallbackDelay = delay3;
+  }
+  delay2.fallback = fallback;
+})(delay || (delay = {}));
+async function never(p) {
+  if (p)
+    console.warn(`Promise is being called via "never", please ensure this doesn't get deployed!`, p);
+  return new Promise(() => {
+  });
+}
+export {
+  assert,
+  delay,
+  never
+};

package/dist/promises/__tests__/assert.spec.d.ts

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

package/dist/promises/__tests__/delay.spec.d.ts

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

package/dist/promises/__tests__/never.spec.d.ts

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

package/dist/promises/assert.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ensures a promise matches the given predicate
+ * @returns The original promise
+ */
+export declare function assert<P extends Promise<any>, V = P extends Promise<infer V> ? V : never>(p: P, predicate: (value: V) => boolean, message?: string): Promise<V>;
+export declare namespace assert {
+    /**
+     * Ensures a promise result is defined
+     * @returns The original promise
+     */
+    function defined<P extends Promise<any>, V = Awaited<P>>(p: P, message?: string): Promise<Exclude<V, undefined | null>>;
+}

package/dist/promises/delay.d.ts

@@ -0,0 +1,18 @@
+/**
+ * If requests resolve instantly it can lead to users feeling like nothing *really* happened.
+ * This just ensures a request always takes a *little* bit of time so that spinners and what not can appear.
+ *
+ * @param promise The promise to return upon resolving
+ * @param ms The time to wait
+ * @returns A promise that resolves based on the time specified
+ */
+export declare function delay(): Promise<void>;
+export declare function delay(ms: number): Promise<void>;
+export declare function delay<T>(promise: Promise<T>): Promise<T>;
+export declare function delay<T>(promise: Promise<T>, ms: number): Promise<T>;
+export declare namespace delay {
+    /**
+     * Overrides the default delay value
+     */
+    function fallback(delay: number): void;
+}

package/dist/promises/index.d.ts

@@ -0,0 +1,3 @@
+export * from './assert';
+export * from './delay';
+export * from './never';

package/dist/promises/never.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Purely for testing spinners / skeletons
+ * @returns A promise that never resolves
+ */
+export declare function never(p?: Promise<any>): Promise<void>;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ribbon-studios/js-utils",
+  "version": "1.1.1",
+  "description": "Collection of generic javascript utilities curated by the Rainbow Cafe~",
+  "type": "module",
+  "source": "src/*.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.module.js",
+  "unpkg": "./dist/index.umd.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "ci": "bun install --frozen-lockfile",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint 'src/**/*.ts'",
+    "build": "rm -rf dist && vite build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.20",
+    "@typescript-eslint/eslint-plugin": "^7.0.2",
+    "@typescript-eslint/parser": "^7.0.2",
+    "@vitest/coverage-v8": "^1.3.1",
+    "chance": "^1.1.11",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-unused-imports": "^3.1.0",
+    "happy-dom": "^13.5.0",
+    "typescript": "^5.3.3",
+    "vite": "^5.1.4",
+    "vite-plugin-dts": "^3.7.3",
+    "vite-plugin-lib-types": "^3.0.9",
+    "vitest": "^1.3.1",
+    "vitest-dom": "^0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ribbon-studios/js-utils.git"
+  },
+  "license": "MIT"
+}