### ----------------------------------------------------
### -- TinyID
### -- Licenses: Artistic-2.0
### -- Authors: Paweł bbkr Pabian
### -- File: README.md
### ----------------------------------------------------
# Shorten and obfuscate IDs in [Raku](https://www.raku.org) language

[![test](https://github.com/bbkr/TinyID/actions/workflows/test.yml/badge.svg)](https://github.com/bbkr/TinyID/actions/workflows/test.yml)

## SYNOPSIS

```raku
    use TinyID;
    
    my $key = ( 'a'..'z', 'A'..'Z', 0..9 ).flat.pick( * ).join;
    # example key is '2BjLhRduC6Tb8Q5cEk9oxnFaWUDpOlGAgwYzNre7tI4yqPvXm0KSV1fJs3ZiHM'
    
    my $tinyid = TinyID.new( key => $key );
    
    say $tinyid.encode( 48888851145 );  # will print '1FN7Ab'
    say $tinyid.decode( '1FN7Ab' );     # will print 48888851145
```

## DESCRIPTION

With the help of this module you can shorten and obfuscate your IDs at the same time. Useful for:

* Hiding real database IDs in URLs or REST APIs.
* Saving space where it is limited, like in SMS or Push messages.


## METHODS

### new( key => 'qwerty' )

Keyt must consist of at least two unique unicode characters.
The **longer the key** - the **shorter encoded ID** will be.
Encoded ID will be **made exclusively out of characters from the key**.

Choose your key characters wisely, for example:

* For SMS messages generate key from `a-z,A-Z,0-9` range. You will get excellent shortening like `1234567890` -> `380FQs`.
* For NTFS file names generate key from `a-z` range. You will get good shortening and avoid case insensitivity collisions, like `1234567890` -> `iszbmfx`.
* When trolling generate key from Emojis. So `1234567890` will be represented as `😣😄😹😧😋😳`.

### encode( 123 )

Encode unsigned integer into a string.

Note that this should not be considered a strong encryption.
It does not contain consistency checks.
And key is easy to reverse engineer with small amount of encoded/decoded samples given.
Treat it as really, really fast obfuscation only.

### decode( 'rer' )

Decode string back into unsigned integer.

## TRICKS

If you provide sequential characters in key you can convert your numbers to some weird numeric systems, for example base18:

```raku
    TinyID.new( key => '0123456789ABCDEFGH' ).encode( 48888851145 ).say;    # '47F709HFF'
```

## COMPATIBLE COUNTERPARTS

* [Rust](https://crates.io/crates/squishyid) - `SquishyID`
* [Perl](http://search.cpan.org/~bbkr/Integer-Tiny-0.3/lib/Integer/Tiny.pm) - `Integer::Tiny`
* [PHP](https://github.com/krowinski/tinyID) - `TinyID`


