✨ Add head function

docs/api/head/index.md

@@ -0,0 +1,42 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+
+
+## head variable
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Returns all but the last element of the given list or string.
+
+<b>Signature:</b>
+
+```typescript
+head: {
+    (val: string): string;
+    <T extends unknown[]>(val: T): T;
+}
+```
+
+## Example 1
+
+
+```ts
+// String
+head('hello') // 'hell'
+head('h') // ''
+head('') // ''
+
+```
+
+## Example 2
+
+
+```ts
+head([1, 2, 3]) // [1, 2]
+head(['hello', 'world']) // ['hello']
+head(['hello']) // []
+head([]) // []
+
+```
+

docs/api/index.md

@@ -20,6 +20,7 @@
 |  [gte](./gte/) | Returns <code>true</code> if the first argument is greater than or equal to the second; otherwise <code>false</code> |
 |  [has](./has/) | <b><i>(BETA)</i></b> Returns whether or not an object has an own property with the specified name. |
 |  [hasPath](./haspath/) | <b><i>(BETA)</i></b> Returns whether or not a path exists in an object. Only the object's own properties are checked. |
+|  [head](./head/) | <b><i>(BETA)</i></b> Returns all but the last element of the given list or string. |
 |  [identity](./identity/) | <b><i>(BETA)</i></b> Return the parameter supplied to it. |
 |  [inc](./inc/) | Increments its argument. |
 |  [isBigint](./isbigint/) | Whatever argument is type of <code>bigint</code> or not. |

src/head.ts

@@ -0,0 +1,31 @@
+/**
+ * Returns all but the last element of the given list or string.
+ *
+ * @param val - string or any array object
+ * @returns The result of `val.slice(0, -1)`
+ *
+ * @example
+ * ```ts
+ * // String
+ * head('hello') // 'hell'
+ * head('h') // ''
+ * head('') // ''
+ * ```
+ *
+ * @example
+ * ```ts
+ * head([1, 2, 3]) // [1, 2]
+ * head(['hello', 'world']) // ['hello']
+ * head(['hello']) // []
+ * head([]) // []
+ * ```
+ *
+ * @beta
+ */
+const head: {
+  (val: string): string
+  <T extends unknown[]>(val: T): T
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+} = (val: any) => val.slice(0, -1)
+
+export { head }

src/index.ts

@@ -11,6 +11,7 @@ export { gt } from '@/gt'
 export { gte } from '@/gte'
 export { has } from '@/has'
 export { hasPath } from '@/hasPath'
+export { head } from '@/head'
 export { identity } from '@/identity'
 export { inc } from '@/inc'
 export { isBigint } from '@/isBigint'

test/head.spec.ts

@@ -0,0 +1,39 @@
+import { head } from '@/head'
+
+describe('head', () => {
+  const tableString: [string, string][] = [
+    ['', ''],
+    ['a', ''],
+    ['ab', 'a'],
+    ['abc', 'ab']
+  ]
+
+  it.each(tableString)('head(%s) -> %s', (val, expected) => {
+    expect(head(val)).toEqual(expected)
+  })
+
+  const tableArray: [unknown[], unknown[]][] = [
+    [[], []],
+    [[''], []],
+    [[undefined], []],
+    [[null], []],
+    [[0], []],
+    [['', ''], ['']],
+    [[0, 0], [0]],
+    [[0, ''], [0]],
+    [['hello', 'world'], ['hello']],
+    [
+      ['hello', 'new', 'world'],
+      ['hello', 'new']
+    ],
+    [
+      [undefined, null, 'hello', 'world'],
+      [undefined, null, 'hello']
+    ],
+    [[['hello', 'world']], []]
+  ]
+
+  it.each(tableArray)('head(%s) -> %s', (val, expected) => {
+    expect(head(val)).toEqual(expected)
+  })
+})