bespoke

# bespoke

[![Package Version](https://img.shields.io/hexpm/v/bespoke)](https://hex.pm/packages/bespoke)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/bespoke/)

```sh
gleam add bespoke@1
```

## Types

### Bespoke

- A `Bespoke` instance *cannot* be serialized and transmitted over the network.
- It's guarentees do *not* apply across machines, but *do* apply across erlang processes within the same cluster.
- In erlang this is implemented via a `reference`.
- In javascript this is implemented via a `Symbol`.

### SerializableBespoke

- A `SerializableBespoke` instance *can* be serialized and transmitted over the network.
- It's guarentees apply everywhere, but could theoretically be broken.
- Larger memory overhead than a `Bespoke` instance.
- It is represented as a BitArray of 2048 bits split into the time of creation and random number generation.
- Can be shared accross erlang *and* javascript processes.
- On javascript this is implemented via a `Uint32Array`. (This is mutable so avoid editing it!)
- On erlang this is implemented via a `bin`.

## Usage

### Local / Internal guaranteed uniqueness

```gleam
import bespoke

pub fn main() -> Nil {
  let id = bespoke.new()
  let id2 = bespoke.new()
  // id and id2 are guaranteed to be unique
}
```

### Shared / External guaranteed* uniqueness

> **Note**: *Guaranteed uniqueness is not guaranteed as psudo-randomness is utilised

```gleam
import bespoke/serializable as bespoke

pub fn main() -> Nil {
  let key = bespoke.new()
  let stringified = bespoke.serialize(key)

  let assert Ok(parsed) = bespoke.deserialize(stringified)
  assert parsed == key // Will be parsed to be equal to the original key
}
```

## Supported runtimes

|Runtime|Supported|
|-------|---------|
|Erlang|✅|
|JavaScript|✅|
|Deno|✅|
|Bun|✅|

## Contributing

PRs are welcome with or without prior discussion.

## License

This project is licensed under the Apache License, Version 2.0.

See [LICENSE](LICENSE) for more information.

## Additional information

If you're unsure about anything, contact me directly via BradBot_1#2042

Further documentation can be found at <https://hexdocs.pm/bespoke>.