@bytebury/toolkit 1.6.0 → 1.8.0

package/esm/src/core.d.ts

@@ -1,4 +1,3 @@
-import type { NonEmptyList } from "./utility_types.js";
 /**
  * Clone an object using structuredClone.
  */
@@ -23,31 +22,33 @@ export declare function isEqual(thing1: unknown, thing2: unknown): boolean;
  * is a string, then it will return the first character.
  *
  * @remarks
- * If an empty list is passed then this will return undefined.
+ * If an empty list or string is passed then this will return undefined.
  *
  * @example
  * ```ts
  * first("hello"); // "h"
  * first([1, 2, 3]); // 1
+ * first([]); // undefined
  * ```
  */
-export declare function first<T>(list: NonEmptyList<T>): T;
-export declare function first(value: string): string;
+export declare function first(value: string): string | undefined;
+export declare function first<T>(list: T[]): T | undefined;
 /**
  * Returns the last thing in a list. If the value
  * is a string, then it will return the last character.
  *
  * @remarks
- * If an empty list is passed then this will return undefined.
+ * If an empty list or string is passed then this will return undefined.
  *
  * @example
  * ```ts
  * last("hello"); // "o"
  * last([1, 2, 3]); // 3
+ * last([]); // undefined
  * ```
  */
-export declare function last<T>(list: NonEmptyList<T>): T;
-export declare function last(value: string): string;
+export declare function last(value: string): string | undefined;
+export declare function last<T>(list: T[]): T | undefined;
 /**
  * Compares two things by turning them into strings,
  * and comparing them by their string value.
@@ -161,7 +162,6 @@ export declare function reverse<T>(thing: Set<T>): Set<T>;
  * isEmpty(new Map()); // true
  * ```
  */
-export declare function isEmpty(thing: unknown[]): boolean;
 export declare function isEmpty(thing: unknown): boolean;
 /**
  * Determines if the given thing is not empty.
@@ -179,7 +179,6 @@ export declare function isEmpty(thing: unknown): boolean;
  * isNotEmpty(new Map()); // false
  * ```
  */
-export declare function isNotEmpty(thing: unknown[]): boolean;
 export declare function isNotEmpty(thing: unknown): boolean;
 /**
  * Returns the distinct values from a list.
@@ -220,7 +219,7 @@ export declare function distinct<T>(list: T[]): T[];
  * console.log(sample([])); // undefined
  * ```
  */
-export declare function sample<T>(list: NonEmptyList<T>): T;
+export declare function sample<T>(list: T[]): T | undefined;
 /**
  * Gives a random number in the given range. The first parameter is inclusive
  * and the second one is exclusive. Therefore, it will work with lists out of
@@ -365,6 +364,9 @@ export declare function intersection<T>(...lists: T[][]): T[];
  * If `searchFor` is an empty list, this returns `true` (vacuously, since
  * every item in an empty list is found).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includes("hello world", "hello"); // true
@@ -374,9 +376,11 @@ export declare function intersection<T>(...lists: T[][]): T[];
  * includes(["a", "b", "c"], ["a", "b"]); // true
  * includes(["a", "b", "c"], ["a", "d"]); // false
  * includes("hello world", []); // true
+ * includes(null, "hello"); // false
+ * includes("hello world", undefined); // false
  * ```
  */
-export declare function includes(searchIn: string | string[], searchFor: string | string[]): boolean;
+export declare function includes(searchIn: string | string[] | null | undefined, searchFor: string | string[] | null | undefined): boolean;
 /**
  * Determines if `searchIn` contains any of the given `searchFor` term(s).
  *
@@ -388,6 +392,9 @@ export declare function includes(searchIn: string | string[], searchFor: string
  * If `searchFor` is an empty list, this returns `false` (there is no term
  * to match).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includesAny("hello world", "hello"); // true
@@ -397,7 +404,9 @@ export declare function includes(searchIn: string | string[], searchFor: string
  * includesAny(["a", "b", "c"], ["a", "d"]); // true
  * includesAny(["a", "b", "c"], ["d", "e"]); // false
  * includesAny("hello world", []); // false
+ * includesAny(null, "hello"); // false
+ * includesAny("hello world", undefined); // false
  * ```
  */
-export declare function includesAny(searchIn: string | string[], searchFor: string | string[]): boolean;
+export declare function includesAny(searchIn: string | string[] | null | undefined, searchFor: string | string[] | null | undefined): boolean;
 //# sourceMappingURL=core.d.ts.map

package/esm/src/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/src/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/src/core.ts"],"names":[],"mappings":"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"}

package/esm/src/core.js

@@ -128,6 +128,25 @@ export function reverse(thing) {
         return new Set([...thing].reverse());
     return thing.reverse();
 }
+/**
+ * Determines if the given thing is empty.
+ *
+ * Things are empty when:
+ *   * They are `None`
+ *   * They are empty strings
+ *   * They have no length or size
+ *
+ * @example
+ * ```ts
+ * isEmpty([]); // true
+ * isEmpty([0]); // false
+ * isEmpty(""); // true
+ * isEmpty(" "); // false
+ * isEmpty(new Set()); // true
+ * isEmpty({}); // true
+ * isEmpty(new Map()); // true
+ * ```
+ */
 export function isEmpty(thing) {
     if (isNone(thing))
         return true;
@@ -141,6 +160,22 @@ export function isEmpty(thing) {
         return Object.keys(thing).length === 0;
     return false;
 }
+/**
+ * Determines if the given thing is not empty.
+ *
+ * @remarks this is the inverse of `isEmpty`.
+ *
+ * @example
+ * ```ts
+ * isNotEmpty([]); // false
+ * isNotEmpty([0]); // true
+ * isNotEmpty(""); // false
+ * isNotEmpty(" "); // true
+ * isNotEmpty(new Set()); // false
+ * isNotEmpty({}); // false
+ * isNotEmpty(new Map()); // false
+ * ```
+ */
 export function isNotEmpty(thing) {
     return !isEmpty(thing);
 }
@@ -376,6 +411,9 @@ export function intersection(...lists) {
  * If `searchFor` is an empty list, this returns `true` (vacuously, since
  * every item in an empty list is found).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includes("hello world", "hello"); // true
@@ -385,9 +423,13 @@ export function intersection(...lists) {
  * includes(["a", "b", "c"], ["a", "b"]); // true
  * includes(["a", "b", "c"], ["a", "d"]); // false
  * includes("hello world", []); // true
+ * includes(null, "hello"); // false
+ * includes("hello world", undefined); // false
  * ```
  */
 export function includes(searchIn, searchFor) {
+    if (searchIn == null || searchFor == null)
+        return false;
     const terms = Array.isArray(searchFor) ? searchFor : [searchFor];
     return terms.every((term) => searchIn.includes(term));
 }
@@ -402,6 +444,9 @@ export function includes(searchIn, searchFor) {
  * If `searchFor` is an empty list, this returns `false` (there is no term
  * to match).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includesAny("hello world", "hello"); // true
@@ -411,9 +456,13 @@ export function includes(searchIn, searchFor) {
  * includesAny(["a", "b", "c"], ["a", "d"]); // true
  * includesAny(["a", "b", "c"], ["d", "e"]); // false
  * includesAny("hello world", []); // false
+ * includesAny(null, "hello"); // false
+ * includesAny("hello world", undefined); // false
  * ```
  */
 export function includesAny(searchIn, searchFor) {
+    if (searchIn == null || searchFor == null)
+        return false;
     const terms = Array.isArray(searchFor) ? searchFor : [searchFor];
     return terms.some((term) => searchIn.includes(term));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebury/toolkit",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "TypeScript utility library to help energize your projects with useful functions for any size project. Save yourself some time and focus on shipping features.",
   "repository": {
     "type": "git",

package/script/src/core.d.ts

@@ -1,4 +1,3 @@
-import type { NonEmptyList } from "./utility_types.js";
 /**
  * Clone an object using structuredClone.
  */
@@ -23,31 +22,33 @@ export declare function isEqual(thing1: unknown, thing2: unknown): boolean;
  * is a string, then it will return the first character.
  *
  * @remarks
- * If an empty list is passed then this will return undefined.
+ * If an empty list or string is passed then this will return undefined.
  *
  * @example
  * ```ts
  * first("hello"); // "h"
  * first([1, 2, 3]); // 1
+ * first([]); // undefined
  * ```
  */
-export declare function first<T>(list: NonEmptyList<T>): T;
-export declare function first(value: string): string;
+export declare function first(value: string): string | undefined;
+export declare function first<T>(list: T[]): T | undefined;
 /**
  * Returns the last thing in a list. If the value
  * is a string, then it will return the last character.
  *
  * @remarks
- * If an empty list is passed then this will return undefined.
+ * If an empty list or string is passed then this will return undefined.
  *
  * @example
  * ```ts
  * last("hello"); // "o"
  * last([1, 2, 3]); // 3
+ * last([]); // undefined
  * ```
  */
-export declare function last<T>(list: NonEmptyList<T>): T;
-export declare function last(value: string): string;
+export declare function last(value: string): string | undefined;
+export declare function last<T>(list: T[]): T | undefined;
 /**
  * Compares two things by turning them into strings,
  * and comparing them by their string value.
@@ -161,7 +162,6 @@ export declare function reverse<T>(thing: Set<T>): Set<T>;
  * isEmpty(new Map()); // true
  * ```
  */
-export declare function isEmpty(thing: unknown[]): boolean;
 export declare function isEmpty(thing: unknown): boolean;
 /**
  * Determines if the given thing is not empty.
@@ -179,7 +179,6 @@ export declare function isEmpty(thing: unknown): boolean;
  * isNotEmpty(new Map()); // false
  * ```
  */
-export declare function isNotEmpty(thing: unknown[]): boolean;
 export declare function isNotEmpty(thing: unknown): boolean;
 /**
  * Returns the distinct values from a list.
@@ -220,7 +219,7 @@ export declare function distinct<T>(list: T[]): T[];
  * console.log(sample([])); // undefined
  * ```
  */
-export declare function sample<T>(list: NonEmptyList<T>): T;
+export declare function sample<T>(list: T[]): T | undefined;
 /**
  * Gives a random number in the given range. The first parameter is inclusive
  * and the second one is exclusive. Therefore, it will work with lists out of
@@ -365,6 +364,9 @@ export declare function intersection<T>(...lists: T[][]): T[];
  * If `searchFor` is an empty list, this returns `true` (vacuously, since
  * every item in an empty list is found).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includes("hello world", "hello"); // true
@@ -374,9 +376,11 @@ export declare function intersection<T>(...lists: T[][]): T[];
  * includes(["a", "b", "c"], ["a", "b"]); // true
  * includes(["a", "b", "c"], ["a", "d"]); // false
  * includes("hello world", []); // true
+ * includes(null, "hello"); // false
+ * includes("hello world", undefined); // false
  * ```
  */
-export declare function includes(searchIn: string | string[], searchFor: string | string[]): boolean;
+export declare function includes(searchIn: string | string[] | null | undefined, searchFor: string | string[] | null | undefined): boolean;
 /**
  * Determines if `searchIn` contains any of the given `searchFor` term(s).
  *
@@ -388,6 +392,9 @@ export declare function includes(searchIn: string | string[], searchFor: string
  * If `searchFor` is an empty list, this returns `false` (there is no term
  * to match).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includesAny("hello world", "hello"); // true
@@ -397,7 +404,9 @@ export declare function includes(searchIn: string | string[], searchFor: string
  * includesAny(["a", "b", "c"], ["a", "d"]); // true
  * includesAny(["a", "b", "c"], ["d", "e"]); // false
  * includesAny("hello world", []); // false
+ * includesAny(null, "hello"); // false
+ * includesAny("hello world", undefined); // false
  * ```
  */
-export declare function includesAny(searchIn: string | string[], searchFor: string | string[]): boolean;
+export declare function includesAny(searchIn: string | string[] | null | undefined, searchFor: string | string[] | null | undefined): boolean;
 //# sourceMappingURL=core.d.ts.map

package/script/src/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/src/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/src/core.ts"],"names":[],"mappings":"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"}

package/script/src/core.js

@@ -159,6 +159,25 @@ function reverse(thing) {
         return new Set([...thing].reverse());
     return thing.reverse();
 }
+/**
+ * Determines if the given thing is empty.
+ *
+ * Things are empty when:
+ *   * They are `None`
+ *   * They are empty strings
+ *   * They have no length or size
+ *
+ * @example
+ * ```ts
+ * isEmpty([]); // true
+ * isEmpty([0]); // false
+ * isEmpty(""); // true
+ * isEmpty(" "); // false
+ * isEmpty(new Set()); // true
+ * isEmpty({}); // true
+ * isEmpty(new Map()); // true
+ * ```
+ */
 function isEmpty(thing) {
     if (isNone(thing))
         return true;
@@ -172,6 +191,22 @@ function isEmpty(thing) {
         return Object.keys(thing).length === 0;
     return false;
 }
+/**
+ * Determines if the given thing is not empty.
+ *
+ * @remarks this is the inverse of `isEmpty`.
+ *
+ * @example
+ * ```ts
+ * isNotEmpty([]); // false
+ * isNotEmpty([0]); // true
+ * isNotEmpty(""); // false
+ * isNotEmpty(" "); // true
+ * isNotEmpty(new Set()); // false
+ * isNotEmpty({}); // false
+ * isNotEmpty(new Map()); // false
+ * ```
+ */
 function isNotEmpty(thing) {
     return !isEmpty(thing);
 }
@@ -407,6 +442,9 @@ function intersection(...lists) {
  * If `searchFor` is an empty list, this returns `true` (vacuously, since
  * every item in an empty list is found).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includes("hello world", "hello"); // true
@@ -416,9 +454,13 @@ function intersection(...lists) {
  * includes(["a", "b", "c"], ["a", "b"]); // true
  * includes(["a", "b", "c"], ["a", "d"]); // false
  * includes("hello world", []); // true
+ * includes(null, "hello"); // false
+ * includes("hello world", undefined); // false
  * ```
  */
 function includes(searchIn, searchFor) {
+    if (searchIn == null || searchFor == null)
+        return false;
     const terms = Array.isArray(searchFor) ? searchFor : [searchFor];
     return terms.every((term) => searchIn.includes(term));
 }
@@ -433,6 +475,9 @@ function includes(searchIn, searchFor) {
  * If `searchFor` is an empty list, this returns `false` (there is no term
  * to match).
  *
+ * If either `searchIn` or `searchFor` is `null` or `undefined`, this
+ * returns `false`.
+ *
  * @example
  * ```ts
  * includesAny("hello world", "hello"); // true
@@ -442,9 +487,13 @@ function includes(searchIn, searchFor) {
  * includesAny(["a", "b", "c"], ["a", "d"]); // true
  * includesAny(["a", "b", "c"], ["d", "e"]); // false
  * includesAny("hello world", []); // false
+ * includesAny(null, "hello"); // false
+ * includesAny("hello world", undefined); // false
  * ```
  */
 function includesAny(searchIn, searchFor) {
+    if (searchIn == null || searchFor == null)
+        return false;
     const terms = Array.isArray(searchFor) ? searchFor : [searchFor];
     return terms.some((term) => searchIn.includes(term));
 }