@xylabs/hex 4.13.19 → 4.13.21

package/README.md

@@ -12,13 +12,696 @@
 [![snyk-badge][]][snyk-link]
 [![socket-badge][]][socket-link]
 
-Version: 4.13.15
 
 Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
-## Documentation
+## API Documentation
+
+**@xylabs/hex**
+
+***
+
+## Interfaces
+
+- [HexConfig](#interfaces/HexConfig)
+
+## Type Aliases
+
+- [Address](#type-aliases/Address)
+- [HashBitLength](#type-aliases/HashBitLength)
+- [Hash](#type-aliases/Hash)
+- [Hex](#type-aliases/Hex)
+
+## Variables
+
+- [ZERO\_ADDRESS](#variables/ZERO_ADDRESS)
+- [ZERO\_HASH](#variables/ZERO_HASH)
+- [HashBitLength](#variables/HashBitLength)
+- [hexRegex](#variables/hexRegex)
+- [hexRegexWithPrefix](#variables/hexRegexWithPrefix)
+
+## Functions
+
+- [toAddress](#functions/toAddress)
+- [isAddress](#functions/isAddress)
+- [asAddress](#functions/asAddress)
+- [isHashBitLength](#functions/isHashBitLength)
+- [isHash](#functions/isHash)
+- [asHash](#functions/asHash)
+- [asHex](#functions/asHex)
+- [hexFrom](#functions/hexFrom)
+- [hexFromArrayBuffer](#functions/hexFromArrayBuffer)
+- [hexFromBigInt](#functions/hexFromBigInt)
+- [hexFromHexString](#functions/hexFromHexString)
+- [hexFromNumber](#functions/hexFromNumber)
+- [isHex](#functions/isHex)
+- [isHexZero](#functions/isHexZero)
+- [toHexLegacy](#functions/toHexLegacy)
+- [bitsToNibbles](#functions/bitsToNibbles)
+- [nibblesToBits](#functions/nibblesToBits)
+- [toHex](#functions/toHex)
+- [hexToBigInt](#functions/hexToBigInt)
+
+### functions
+
+  ### <a id="asAddress"></a>asAddress
+
+[**@xylabs/hex**](#../README)
+
+***
+
+## Call Signature
+
+```ts
+function asAddress(value): undefined | Lowercase<string>;
+```
+
+### Parameters
+
+### value
+
+`unknown`
+
+### Returns
+
+`undefined` \| `Lowercase`\<`string`\>
+
+## Call Signature
+
+```ts
+function asAddress(value, assert): Lowercase<string>;
+```
+
+### Parameters
+
+### value
+
+`unknown`
+
+### assert
+
+`AssertConfig`
+
+### Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="asHash"></a>asHash
+
+[**@xylabs/hex**](#../README)
+
+***
+
+## Call Signature
+
+```ts
+function asHash(value): undefined | Lowercase<string>;
+```
+
+### Parameters
+
+### value
+
+`unknown`
+
+### Returns
+
+`undefined` \| `Lowercase`\<`string`\>
+
+## Call Signature
+
+```ts
+function asHash(value, assert): Lowercase<string>;
+```
+
+### Parameters
+
+### value
+
+`unknown`
+
+### assert
+
+`AssertConfig`
+
+### Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="asHex"></a>asHex
+
+[**@xylabs/hex**](#../README)
+
+***
+
+## Call Signature
+
+```ts
+function asHex(value): undefined | Lowercase<string>;
+```
+
+### Parameters
+
+### value
+
+`unknown`
+
+### Returns
+
+`undefined` \| `Lowercase`\<`string`\>
+
+## Call Signature
+
+```ts
+function asHex(value, assert): Lowercase<string>;
+```
+
+### Parameters
+
+### value
+
+`unknown`
+
+### assert
+
+`AssertConfig`
+
+### Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="bitsToNibbles"></a>bitsToNibbles
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function bitsToNibbles(value): number;
+```
+
+## Parameters
+
+### value
+
+`number`
+
+## Returns
+
+`number`
+
+  ### <a id="hexFrom"></a>hexFrom
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function hexFrom(value, config?): Lowercase<string>;
+```
+
+Takes unknown value and tries our best to convert it to a hex string
+
+## Parameters
+
+### value
+
+Supported types are string, number, bigint, and ArrayBuffer
+
+`string` | `number` | `bigint` | `ArrayBufferLike`
+
+### config?
+
+[`HexConfig`](#../interfaces/HexConfig)
+
+Configuration of output format and validation
+
+## Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="hexFromArrayBuffer"></a>hexFromArrayBuffer
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function hexFromArrayBuffer(buffer, config?): Lowercase<string>;
+```
+
+Convert an ArrayBuffer to a hex string
+
+## Parameters
+
+### buffer
+
+`ArrayBufferLike`
+
+The buffer to be converted
+
+### config?
+
+[`HexConfig`](#../interfaces/HexConfig)
+
+Configuration of output format and validation
+
+## Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="hexFromBigInt"></a>hexFromBigInt
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function hexFromBigInt(value, config): Lowercase<string>;
+```
+
+Convert a bigint to a hex string
+
+## Parameters
+
+### value
+
+`bigint`
+
+The bigint to be converted
+
+### config
+
+[`HexConfig`](#../interfaces/HexConfig) = `{}`
+
+Configuration of output format and validation
+
+## Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="hexFromHexString"></a>hexFromHexString
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function hexFromHexString(value, config): Lowercase<string>;
+```
+
+## Parameters
+
+### value
+
+`string`
+
+### config
+
+[`HexConfig`](#../interfaces/HexConfig) = `{}`
+
+## Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="hexFromNumber"></a>hexFromNumber
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function hexFromNumber(value, config?): Lowercase<string>;
+```
+
+## Parameters
+
+### value
+
+`number`
+
+### config?
+
+[`HexConfig`](#../interfaces/HexConfig)
+
+## Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="hexToBigInt"></a>hexToBigInt
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function hexToBigInt(hex): bigint;
+```
+
+## Parameters
+
+### hex
+
+`Lowercase`\<`string`\>
+
+## Returns
+
+`bigint`
+
+  ### <a id="isAddress"></a>isAddress
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function isAddress(value, config): value is Lowercase<string>;
+```
+
+## Parameters
+
+### value
+
+`unknown`
+
+### config
+
+[`HexConfig`](#../interfaces/HexConfig) = `{}`
+
+## Returns
+
+`value is Lowercase<string>`
+
+  ### <a id="isHash"></a>isHash
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function isHash(value, bitLength): value is Lowercase<string>;
+```
+
+## Parameters
+
+### value
+
+`unknown`
+
+### bitLength
+
+[`HashBitLength`](#../type-aliases/HashBitLength) = `256`
+
+## Returns
+
+`value is Lowercase<string>`
+
+  ### <a id="isHashBitLength"></a>isHashBitLength
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function isHashBitLength(value): value is HashBitLength;
+```
+
+## Parameters
+
+### value
+
+`unknown`
+
+## Returns
+
+`value is HashBitLength`
+
+  ### <a id="isHex"></a>isHex
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function isHex(value, config?): value is Lowercase<string>;
+```
+
+## Parameters
+
+### value
+
+`unknown`
+
+### config?
+
+[`HexConfig`](#../interfaces/HexConfig)
+
+## Returns
+
+`value is Lowercase<string>`
+
+  ### <a id="isHexZero"></a>isHexZero
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function isHexZero(value?): undefined | boolean;
+```
+
+## Parameters
+
+### value?
+
+`string`
+
+## Returns
+
+`undefined` \| `boolean`
+
+  ### <a id="nibblesToBits"></a>nibblesToBits
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function nibblesToBits(value): number;
+```
+
+## Parameters
+
+### value
+
+`number`
+
+## Returns
+
+`number`
+
+  ### <a id="toAddress"></a>toAddress
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function toAddress(value, config): Lowercase<string>;
+```
+
+## Parameters
+
+### value
+
+`string` | `number` | `bigint` | `ArrayBufferLike`
+
+### config
+
+[`HexConfig`](#../interfaces/HexConfig) = `{}`
+
+## Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="toHex"></a>toHex
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function toHex(value, config): Lowercase<string>;
+```
+
+takes any value and tries our best to convert it to a hex string
+
+## Parameters
+
+### value
+
+Supported types are string, number, bigint, and ArrayBuffer
+
+`string` | `number` | `bigint` | `ArrayBufferLike`
+
+### config
+
+[`HexConfig`](#../interfaces/HexConfig) = `{}`
+
+Configuration of output format and validation
+
+## Returns
+
+`Lowercase`\<`string`\>
+
+  ### <a id="toHexLegacy"></a>toHexLegacy
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+function toHexLegacy(buffer): string;
+```
+
+## Parameters
+
+### buffer
+
+`ArrayBuffer`
+
+## Returns
+
+`string`
+
+### interfaces
+
+  ### <a id="HexConfig"></a>HexConfig
+
+[**@xylabs/hex**](#../README)
+
+***
+
+Configuration of validation and output format
+
+## Properties
+
+### bitLength?
+
+```ts
+optional bitLength: number;
+```
+
+***
+
+### byteSize?
+
+```ts
+optional byteSize: number;
+```
+
+***
+
+### prefix?
+
+```ts
+optional prefix: boolean;
+```
+
+### type-aliases
+
+  ### <a id="Address"></a>Address
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+type Address = Exclude<Hex, "reserved-address-value">;
+```
+
+  ### <a id="Hash"></a>Hash
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+type Hash = Exclude<Hex, "reserved-hash-value">;
+```
+
+  ### <a id="HashBitLength"></a>HashBitLength
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+type HashBitLength = 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096;
+```
+
+  ### <a id="Hex"></a>Hex
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+type Hex = Exclude<Lowercase<string>, "reserved-hex-value">;
+```
+
+### variables
+
+  ### <a id="HashBitLength"></a>HashBitLength
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+HashBitLength: HashBitLength[];
+```
+
+  ### <a id="ZERO_ADDRESS"></a>ZERO_ADDRESS
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+const ZERO_ADDRESS: Address;
+```
+
+  ### <a id="ZERO_HASH"></a>ZERO_HASH
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+const ZERO_HASH: Hash;
+```
+
+  ### <a id="hexRegex"></a>hexRegex
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+const hexRegex: RegExp;
+```
+
+  ### <a id="hexRegexWithPrefix"></a>hexRegexWithPrefix
+
+[**@xylabs/hex**](#../README)
+
+***
+
+```ts
+const hexRegexWithPrefix: RegExp;
+```
 
-Coming Soon!
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/hex",
-  "version": "4.13.19",
+  "version": "4.13.21",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "hex",
@@ -29,22 +29,25 @@
   "exports": {
     ".": {
       "types": "./dist/neutral/index.d.ts",
+      "source": "./src/index.ts",
       "default": "./dist/neutral/index.mjs"
     },
     "./package.json": "./package.json"
   },
   "module": "./dist/neutral/index.mjs",
+  "source": "./src/index.ts",
   "types": "./dist/neutral/index.d.ts",
-  "workspaces": [
-    "packages/**/*"
+  "files": [
+    "dist",
+    "src"
   ],
   "dependencies": {
-    "@xylabs/typeof": "^4.13.19"
+    "@xylabs/typeof": "^4.13.21"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "^7.0.0-rc.27",
-    "@xylabs/tsconfig": "^7.0.0-rc.27",
-    "@xylabs/vitest-extended": "^4.13.19",
+    "@xylabs/ts-scripts-yarn3": "^7.0.0",
+    "@xylabs/tsconfig": "^7.0.0",
+    "@xylabs/vitest-extended": "^4.13.21",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },

package/src/spec/address.spec.ts

@@ -0,0 +1,25 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, test,
+} from 'vitest'
+
+import { asAddress, isAddress } from '../address.ts'
+
+describe('address', () => {
+  test('isAddress', () => {
+    expect(isAddress(true)).toBeFalse()
+    expect(isAddress({})).toBeFalse()
+    expect(isAddress('NotHex')).toBeFalse()
+    expect(isAddress('deadbeef')).toBeFalse()
+    expect(isAddress('0xdeadbeef')).toBeFalse()
+    expect(isAddress('0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef', { prefix: true })).toBeTrue()
+    expect(isAddress('0xdeadbeefdeadbeefdeadxxxxdeadbeefdeadbeef')).toBeFalse()
+  })
+  test('asAddress', () => {
+    expect(asAddress('0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef')).toBe('deadbeefdeadbeefdeadbeefdeadbeefdeadbeef')
+    expect(asAddress('deadbeefdeadbeefdeadbeefdeadbeefdeadbeef')).toBe('deadbeefdeadbeefdeadbeefdeadbeefdeadbeef')
+    expect(asAddress('0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef', true)).toBe('deadbeefdeadbeefdeadbeefdeadbeefdeadbeef')
+    expect(asAddress('000000000000000000000000000000000000000a', true)).toBe('000000000000000000000000000000000000000a')
+  })
+})

package/src/spec/hash.spec.ts

@@ -0,0 +1,23 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, test,
+} from 'vitest'
+
+import { isHash } from '../hash.ts'
+import { hexFromNumber } from '../hex/index.ts'
+
+describe('hash', () => {
+  test('isHash', () => {
+    expect(isHash(true)).toBeFalse()
+    expect(isHash({})).toBeFalse()
+    expect(isHash('NotHex')).toBeFalse()
+    expect(isHash('deadbeef')).toBeFalse()
+    expect(isHash('0xdeadbeef')).toBeFalse()
+  })
+  test('hexFromNumber', () => {
+    expect(hexFromNumber(10)).toBe('0a')
+    expect(hexFromNumber(10, { bitLength: 256 })).toBe('000000000000000000000000000000000000000000000000000000000000000a')
+    expect(hexFromNumber(10, { bitLength: 128 })).toBe('0000000000000000000000000000000a')
+  })
+})

package/src/spec/hex.spec.ts

@@ -0,0 +1,24 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, test,
+} from 'vitest'
+
+import {
+  hexFromArrayBuffer, hexFromNumber, isHex,
+} from '../hex/index.ts'
+
+describe('hex', () => {
+  test('isHex', () => {
+    expect(isHex(true)).toBeFalse()
+    expect(isHex({})).toBeFalse()
+    expect(isHex('NotHex')).toBeFalse()
+    expect(isHex('deadbeef')).toBeTrue()
+    expect(isHex('0xdeadbeef')).toBeFalse()
+  })
+  test('asHex', () => {
+    expect(hexFromArrayBuffer(new ArrayBuffer(2))).toBe('0000')
+    expect(hexFromNumber(10)).toBe('0a')
+    expect(hexFromNumber(10, { bitLength: 256 })).toBe('000000000000000000000000000000000000000000000000000000000000000a')
+  })
+})

package/xy.config.ts

@@ -1,10 +0,0 @@
-import type { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
-const config: XyTsupConfig = {
-  compile: {
-    browser: {},
-    neutral: { src: true },
-    node: {},
-  },
-}
-
-export default config