Lady’s Gitweb - Pisces/blob - collection.js

   1 // ♓🌟 Piscēs ∷ collection.js
   2 // ====================================================================
   3 //
   4 // Copyright © 2020–2023 Lady [@ Lady’s Computer].
   5 //
   6 // This Source Code Form is subject to the terms of the Mozilla Public
   7 // License, v. 2.0. If a copy of the MPL was not distributed with this
   8 // file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
   9
  10 import { call, createCallableFunction } from "./function.js";
  11 import { isConcatSpreadableObject } from "./object.js";
  12 import { toIndex, type } from "./value.js";
  13
  14 const { prototype: arrayPrototype } = Array;
  15
  16 export const {
  17   /** Returns an array of the provided values. */
  18   of: array,
  19
  20   /** Returns whether the provided value is an array. */
  21   isArray,
  22
  23   /** Returns an array created from the provided arraylike. */
  24   from: toArray,
  25 } = Array;
  26
  27 /**
  28  * Returns the result of catenating the provided arraylikes into a new
  29  * collection according to the algorithm of `Array::concat`.
  30  */
  31 export const catenate = createCallableFunction(
  32   arrayPrototype.concat,
  33   "catenate",
  34 );
  35
  36 /**
  37  * Copies the items in the provided object to a new location according
  38  * to the algorithm of `Array::copyWithin`.
  39  */
  40 export const copyWithin = createCallableFunction(
  41   arrayPrototype.copyWithin,
  42 );
  43
  44 /**
  45  * Fills the provided object with the provided value according to the
  46  * algorithm of `Array::fill`.
  47  */
  48 export const fill = createCallableFunction(arrayPrototype.fill);
  49
  50 /**
  51  * Returns the result of filtering the provided object with the
  52  * provided callback, according to the algorithm of `Array::filter`.
  53  */
  54 export const filter = createCallableFunction(arrayPrototype.filter);
  55
  56 /**
  57  * Returns the first index in the provided object whose value satisfies
  58  * the provided callback according to the algorithm of
  59  * `Array::findIndex`.
  60  */
  61 export const findIndex = createCallableFunction(
  62   arrayPrototype.findIndex,
  63 );
  64
  65 /**
  66  * Returns the first indexed entry in the provided object whose value
  67  * satisfies the provided callback.
  68  *
  69  * If a third argument is supplied, it will be used as the this value
  70  * of the callback.
  71  */
  72 export const findIndexedEntry = (
  73   $,
  74   callback,
  75   thisArg = undefined,
  76 ) => {
  77   let result = undefined;
  78   findItem($, (kValue, k, O) => {
  79     if (call(callback, thisArg, [kValue, k, O])) {
  80       // The callback succeeded.
  81       result = [k, kValue];
  82       return true;
  83     } else {
  84       // The callback failed.
  85       return false;
  86     }
  87   });
  88   return result;
  89 };
  90
  91 /**
  92  * Returns the first indexed value in the provided object which
  93  * satisfies the provided callback, according to the algorithm of
  94  * `Array::find`.
  95  */
  96 export const findItem = createCallableFunction(
  97   arrayPrototype.find,
  98   "findItem",
  99 );
 100
 101 /**
 102  * Returns the result of flatmapping the provided value with the
 103  * provided callback according to the algorithm of `Array::flatMap`.
 104  */
 105 export const flatmap = createCallableFunction(
 106   arrayPrototype.flatMap,
 107   "flatmap",
 108 );
 109
 110 /**
 111  * Returns the result of flattening the provided object according to
 112  * the algorithm of `Array::flat`.
 113  */
 114 export const flatten = createCallableFunction(
 115   arrayPrototype.flat,
 116   "flatten",
 117 );
 118
 119 /**
 120  * Returns the first index of the provided object with a value
 121  * equivalent to the provided value according to the algorithm of
 122  * `Array::indexOf`.
 123  */
 124 export const getFirstIndex = createCallableFunction(
 125   arrayPrototype.indexOf,
 126   "getFirstIndex",
 127 );
 128
 129 /**
 130  * Returns the item on the provided object at the provided index
 131  * according to the algorithm of `Array::at`.
 132  */
 133 export const getItem = createCallableFunction(
 134   arrayPrototype.at,
 135   "getItem",
 136 );
 137
 138 /**
 139  * Returns the last index of the provided object with a value
 140  * equivalent to the provided value according to the algorithm of
 141  * `Array::lastIndexOf`.
 142  */
 143 export const getLastIndex = createCallableFunction(
 144   arrayPrototype.lastIndexOf,
 145   "getLastIndex",
 146 );
 147
 148 /**
 149  * Returns whether every indexed value in the provided object satisfies
 150  * the provided function, according to the algorithm of `Array::every`.
 151  */
 152 export const hasEvery = createCallableFunction(
 153   arrayPrototype.every,
 154   "hasEvery",
 155 );
 156
 157 /**
 158  * Returns whether the provided object has an indexed value which
 159  * satisfies the provided function, according to the algorithm of
 160  * `Array::some`.
 161  */
 162 export const hasSome = createCallableFunction(
 163   arrayPrototype.some,
 164   "hasSome",
 165 );
 166
 167 /**
 168  * Returns whether the provided object has an indexed value equivalent
 169  * to the provided value according to the algorithm of
 170  * `Array::includes`.
 171  *
 172  * ※ This algorithm treats missing values as `undefined` rather than
 173  * skipping them.
 174  */
 175 export const includes = createCallableFunction(
 176   arrayPrototype.includes,
 177 );
 178
 179 /**
 180  * Returns an iterator over the indexed entries in the provided value
 181  * according to the algorithm of `Array::entries`.
 182  */
 183 export const indexedEntries = createCallableFunction(
 184   arrayPrototype.entries,
 185   "indexedEntries",
 186 );
 187
 188 /**
 189  * Returns an iterator over the indices in the provided value according
 190  * to the algorithm of `Array::keys`.
 191  */
 192 export const indices = createCallableFunction(
 193   arrayPrototype.keys,
 194   "indices",
 195 );
 196
 197 /**
 198  * Returns whether the provided object is a collection.
 199  *
 200  * The definition of “collection” used by Piscēs is similar to
 201  * Ecmascript’s definition of an arraylike object, but it differs in
 202  * a few ways :—
 203  *
 204  * - It requires the provided value to be a proper object.
 205  *
 206  * - It requires the `length` property to be an integer index.
 207  *
 208  * - It requires the object to be concat‐spreadable, meaning it must
 209  *   either be an array or have `.[Symbol.isConcatSpreadable]` be true.
 210  */
 211 export const isCollection = ($) => {
 212   if (!(type($) === "object" && "length" in $)) {
 213     // The provided value is not an object or does not have a `length`.
 214     return false;
 215   } else {
 216     try {
 217       toIndex($.length); // will throw if `length` is not an index
 218       return isConcatSpreadableObject($);
 219     } catch {
 220       return false;
 221     }
 222   }
 223 };
 224
 225 /**
 226  * Returns an iterator over the items in the provided value according
 227  * to the algorithm of `Array::values`.
 228  */
 229 export const items = createCallableFunction(
 230   arrayPrototype.values,
 231   "items",
 232 );
 233
 234 /**
 235  * Returns the result of mapping the provided value with the provided
 236  * callback according to the algorithm of `Array::map`.
 237  */
 238 export const map = createCallableFunction(arrayPrototype.map);
 239
 240 /**
 241  * Pops from the provided value according to the algorithm of
 242  * `Array::pop`.
 243  */
 244 export const pop = createCallableFunction(arrayPrototype.pop);
 245
 246 /**
 247  * Pushes onto the provided value according to the algorithm of
 248  * `Array::push`.
 249  */
 250 export const push = createCallableFunction(arrayPrototype.push);
 251
 252 /**
 253  * Returns the result of reducing the provided value with the provided
 254  * callback, according to the algorithm of `Array::reduce`.
 255  */
 256 export const reduce = createCallableFunction(arrayPrototype.reduce);
 257
 258 /**
 259  * Reverses the provided value according to the algorithm of
 260  * `Array::reverse`.
 261  */
 262 export const reverse = createCallableFunction(arrayPrototype.reverse);
 263
 264 /**
 265  * Shifts the provided value according to the algorithm of
 266  * `Array::shift`.
 267  */
 268 export const shift = createCallableFunction(arrayPrototype.shift);
 269
 270 /**
 271  * Returns a slice of the provided value according to the algorithm of
 272  * `Array::slice`.
 273  */
 274 export const slice = createCallableFunction(arrayPrototype.slice);
 275
 276 /**
 277  * Sorts the provided value in‐place according to the algorithm of
 278  * `Array::sort`.
 279  */
 280 export const sort = createCallableFunction(arrayPrototype.sort);
 281
 282 /**
 283  * Splices into and out of the provided value according to the
 284  * algorithm of `Array::splice`.
 285  */
 286 export const splice = createCallableFunction(arrayPrototype.splice);
 287
 288 /**
 289  * Unshifts the provided value according to the algorithm of
 290  * `Array::unshift`.
 291  */
 292 export const unshift = createCallableFunction(arrayPrototype.unshift);