Merge pull request #4 from The-Ticking-Clockwork/devel

Merge fix for Nim 2.2.0

.github/workflows/docs.yml

@@ -47,10 +47,10 @@ jobs:
         uses: actions/configure-pages@v3
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           path: ${{ env.deploy-dir }}
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v1
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -0,0 +1,42 @@
+name: Run Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - '**'
+
+env:
+  nim-version: 'stable'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: jiro4989/setup-nim-action@v1
+        with:
+          nim-version: ${{ env.nim-version }}
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - run: nimble install -Y
+
+      - name: Run Tests C (Normal Usage)
+        run: nimble test
+
+      - name: Run Tests C (Locks Disabled)
+        run: nimble test -d:nulidNoLocks
+
+      - name: Run Tests C (Insecure Random)
+        run: nimble test -d:nulidInsecureRandom
+
+      - name: Run Tests C (Insecure Random & Locks Disabled)
+        run: nimble test -d:nulidInsecureRandom -d:nulidNoLocks
+
+      - name: Run Tests JS (Normal Usage; Locks Disabled by Default)
+        run: nimble test -b:js
+
+      - name: Run Tests JS (Insecure Random)
+        run: nimble test -b:js -d:nulidInsecureRandom

.gitignore

@@ -1,2 +1,3 @@
+tests/test1.js
 tests/test1
 htmldocs/

README.md

@@ -1,11 +1,25 @@
 # NULID
 This is an implementation of the [ULID](https://github.com/ulid/spec)
-spec in Nim!
+spec in Nim! This also supports the JS backend for ULID generation!
+
+This supports [`jsony`](https://github.com/treeform/jsony) and
+[`debby`](https://github.com/treeform/debby) out of the box too!
+
+Random fun fact: I coded the initial code for ULID generation on my phone
+via Termux!
+
+## Compile Flags
+`-d:nulidInsecureRandom`: Uses `std/random` instead of `std/sysrand`.
+
+`-d:nulidNoLocks`: Disables any usage of locks within the program.
+
+The JS backend automatically defines `-d:nulidNoLocks`.
+
 
 ## Usage
 ```nim
-let gen = NULIDGenerator()
+let gen = initUlidGenerator()
-let nulid = gen.nulidSync()
+let ulid = gen.ulid()
 
-echo nulid
+echo ulid
 ```

nulid.nimble

@@ -1,6 +1,6 @@
 # Package
 
-version       = "0.2.3"
+version       = "1.3.1"
 author        = "Yu Vitaqua fer Chronos"
 description   = "An implementation of ULID!"
 license       = "CC0"
@@ -11,4 +11,4 @@ srcDir        = "src"
 
 requires "nim >= 2.0.0"
 requires "nint128 >= 0.3.2"
-requires "crockfordb32 >= 1.0.0"
+requires "crockfordb32 >= 2.0.0"

src/nulid.nim

@@ -1,66 +1,140 @@
+{.define: crockfordb32NintSupport.}
+
 import std/[
-  asyncdispatch,
+  times,
-  times
+  json
 ]
 
-import pkg/[
+import crockfordb32
-  crockfordb32,
-  nint128
-]
 
-import ./nulid/private/stew/endians2
+import ./nulid/private/constants
 
-const insecureRandom = defined(nulidInsecureRandom) or defined(js) # No sysrand on the JS backend
+when not defined(js):
+  import std/os
+  import nint128
 
-when insecureRandom:
+  import ./nulid/private/stew/endians2
+
+else:
+  import std/jsbigints
+
+when InsecureRandom:
   import std/random
 
 else:
   import std/sysrand
 
-const HighUint80 = u128("1208925819614629174706176")
+when not NoLocks:
+  import std/rlocks
+
+##[
+Note: There are 2 defines that can be passed to the compiler to trigger different
+functionality in this library at runtime, they are listed here:
+  - `--define:nulidInsecureRandom`: Uses `std/random` instead of `std/sysrand`.
+  - `--define:nulidNoLocks`: Disables the use of locks.
+
+The JS backend used `-d:nulidNoLocks` by default.
+]##
+
+when not defined(js):
+  type UInt128DropIn = UInt128
+
+else:
+  type UInt128DropIn = JsBigInt
 
 type
-  NULID* = object
+  ULIDError* = object of CatchableError
+  ULIDDefect* = object of Defect
+
+  ULIDGenerationError* = object of ULIDError
+  ULIDGenerationDefect* = object of ULIDDefect
+
+  ULID* = object
     ## An object representing a ULID.
-    timestamp*: int64 = 0
+    timestamp*: int64
-    randomness*: UInt128 = 0.u128
+    when not defined(js):
+      randomness*: UInt128
+    else:
+      randomness*: JsBigInt
 
-  NULIDGenerator* = ref object
+  ULIDGenerator* = ref object
-    ## A NULID generator object, contains details needed to follow the spec.
+    ## A `ULID` generator object, contains details needed to follow the spec.
-    ## A generator was made to be compliant with the NULID spec and also to be
+    ## A generator was made to be compliant with the ULID spec and also to be
-    ## threadsafe not use globals that could change.
+    ## threadsafe.
-    lastTime: int64 # Timestamp of last ULID
+    when NoLocks:
-    random: UInt128 # A random number
+      lastTime: int64 # Timestamp of last ULID, 48 bits
+      when not defined(js):
+        random: UInt128 # A random number, 80 bits
+      else:
+        random: JsBigInt
 
-    when insecureRandom:
+      when InsecureRandom:
-      rand: Rand # Random generator when using insecure random
+        rand: Rand # Random generator when using insecure random
 
-proc initNulidGenerator*(): NULIDGenerator =
+    else:
-  ## Initialises a `NULIDGenerator` for use.
+      lock*: RLock
-  result = NULIDGenerator(lastTime: 0, random: 0.u128)
+      lastTime {.guard: lock.}: int64 # Timestamp of last ULID, 48 bits
+      random {.guard: lock.}: UInt128 # A random number, 80 bits
 
-  when insecureRandom:
+      when InsecureRandom:
-    result.rand = initRand()
+        rand {.guard: lock.}: Rand # Random generator when using insecure random
 
-# Discouraged to use it but it's fine for single-threaded apps really
-let globalGen = initNulidGenerator()
 
-func swapBytes(x: Int128): Int128 =
+template withLock(gen: ULIDGenerator, body: typed) =
-  result.lo = swapBytes(cast[uint64](x.hi))
+  when NoLocks:
-  result.hi = cast[int64](swapBytes(x.lo))
+    body
+  else:
+    {.cast(gcsafe).}:
+      acquire(gen.lock)
+
+    {.locks: [gen.lock].}:
+      try:
+        body
+      finally:
+        {.cast(gcsafe).}:
+          release(gen.lock)
+
+
+proc initUlidGenerator*(): ULIDGenerator =
+  ## Initialises a `ULIDGenerator` for use.
+  when NoLocks:
+    result = ULIDGenerator(lastTime: LowInt48, random: LowUint80)
+  else:
+    result = ULIDGenerator(lock: RLock(), lastTime: LowInt48, random: LowUint80)
+    initRLock(result.lock)
+
+  when InsecureRandom:
+    result.withLock:
+      result.rand = initRand()
+
+
+let globalGen = initUlidGenerator()
+
+
+when not defined(js):
+  func swapBytes(x: Int128): Int128 =
+    result.lo = swapBytes(cast[uint64](x.hi))
+    result.hi = cast[int64](swapBytes(x.lo))
+
 
 func toArray[T](oa: openArray[T], size: static Slice[int]): array[size.len, T] =
   result[0..<size.len] = oa[size]
 
-proc randomBits(n: NULIDGenerator): UInt128 =
+
+proc randomBits(n: ULIDGenerator): UInt128DropIn {.gcsafe.} =
   var arr: array[16, byte]
 
-  when insecureRandom:
+  when InsecureRandom:
     var rnd: array[10, byte]
 
-    rnd[0..7] = cast[array[8, byte]](n.rand.next())
+    n.withLock:
-    rnd[8..9] = cast[array[2, byte]](n.rand.rand(high(int16)).int16)
+      when not defined(js):
+        rnd[0..7] = cast[array[8, byte]](n.rand.next())
+        rnd[8..9] = cast[array[2, byte]](n.rand.rand(high(uint16)).uint16)
+
+      else:
+        for i in 0..9:
+          rnd[i] = n.rand.rand(high(byte)).byte
 
     arr[6..15] = rnd
 
@@ -68,118 +142,220 @@ proc randomBits(n: NULIDGenerator): UInt128 =
     var rnd: array[10, byte]
 
     if not urandom(rnd):
-      raise newException(OSError, "Was unable to use a secure source of randomness! " &
+      raise newException(ULIDGenerationDefect, "Was unable to use a secure source of randomness! " &
-        "Please either compile with `-d:nulidInsecureRandom` or fix this!")
+        "Please either compile with `-d:nulidInsecureRandom` or fix this somehow!")
 
     arr[6..15] = rnd
 
-  result = UInt128.fromBytesBE(arr)
+  when not defined(js):
+    result = UInt128.fromBytesBE(arr)
+
+  else:
+    for i in arr:
+      result = result shl 8'big
+      result += big(i)
+
 
 template getTime: int64 = (epochTime() * 1000).int64
 
-proc wait(gen: NULIDGenerator): Future[int64] {.async.} =
-  result = getTime()
 
-  while result <= gen.lastTime:
+proc wait(gen: ULIDGenerator): int64 {.gcsafe.} =
-    await sleepAsync(1)
+  when not defined(js):
     result = getTime()
 
-proc nulid*(gen: NULIDGenerator, timestamp: int64 = 0): Future[NULID] {.async.} =
+    gen.withLock:
-  ## Asynchronously generate a `NULID`.
+      while result <= gen.lastTime:
+        sleep(1)
+        result = getTime()
+
+        if result < gen.lastTime:
+          raise newException(ULIDGenerationError, "Time went backwards!")
+
+  else:
+    raise newException(ULIDGenerationError, "Couldn't generate ULID! Try again in a millisecond.")
+
+
+proc ulid*(gen: ULIDGenerator, timestamp = LowInt48, randomness = LowUint80): ULID {.gcsafe.} =
+  ## Generate a `ULID`, if timestamp is equal to `0`, the `randomness` parameter
+  ## will be ignored.
+  ##
+  ## See also:
+  ## * `ulid(int64, UInt128) <#ulid_2>`_
+  runnableExamples:
+    let gen = initUlidGenerator()
+
+    echo gen.ulid()
+
   if timestamp == 0:
     var now = getTime()
 
-    if now < gen.lastTime:
+    gen.withLock:
-      raise newException(OSError, "Time went backwards!")
+      if gen.lastTime == now:
+        inc gen.random
 
-    if gen.lastTime == now:
+        if gen.random == HighUInt80:
-      inc gen.random
+          now = gen.wait()
+          gen.random = gen.randomBits()
 
-      if gen.random == HighUInt80:
+      else:
-        now = await gen.wait()
+        gen.random = gen.randomBits()
 
-    else:
+      result.randomness = gen.random
-      gen.random = gen.randomBits()
 
     result.timestamp = now
 
   else:
-    result.timestamp = timestamp
+    result.timestamp = clamp(timestamp, LowInt48, HighInt48)
-  result.randomness = gen.random
+    result.randomness = clamp(randomness, LowUint80, HighUint80)
 
-proc nulidSync*(gen: NULIDGenerator, timestamp: int64 = 0): NULID =
-  ## Synchronously generate a `NULID`.
-  result = waitFor gen.nulid(timestamp)
 
-proc nulid*(timestamp: int64 = 0): Future[NULID] =
+proc ulid*(timestamp = LowInt48, randomness = LowUint80): ULID =
-  ## Asynchronously generate a `NULID` using the global generator.
+  ## Generate a `ULID` using the global generator.
-  result = nulid(globalGen, timestamp)
+  ##
-
+  ## See also:
-proc nulidSync*(timestamp: int64 = 0): NULID =
+  ## * `ulid(ULIDGenerator, int64, UInt128) <#ulid,ULIDGenerator>`_
-  ## Synchronously generate a `NULID` using the global generator.
   runnableExamples:
-    echo nulidSync()
+    echo ulid()
 
-  result = waitFor nulid(timestamp)
+  result = ulid(globalGen, timestamp)
 
-func toInt128*(ulid: NULID): Int128 =
+
-  ## Allows for a ULID to be converted to an Int128.
+when not defined(js):
+  func toInt128*(ulid: ULID): Int128 =
+    ## Allows for a `ULID` to be converted to an `Int128`.
+    ##
+    ## **Note:** On the JS backend this returns a `JsBigInt` from `std/jsbigints`
+    runnableExamples:
+      echo ulid().toInt128()
+
+    result = i128(ulid.timestamp) shl 80
+
+    result.hi += cast[int64](ulid.randomness.hi)
+    result.lo += ulid.randomness.lo
+
+
+  func fromInt128*(_: typedesc[ULID], val: Int128): ULID =
+    ## Parses an `Int128` to a `ULID`.
+    ##
+    ## **Note:** On the JS backend this accepts a `JsBigInt` from `std/jsbigints`
+    result.timestamp = (val shr 16).hi
+    result.randomness = UInt128(
+      hi: cast[uint64]((val.hi shl 48) shr 48),
+      lo: val.lo
+    )
+
+
+else:
+  func toInt128*(ulid: ULID): JsBigInt =
+    ## Allows for a `ULID` to be converted to a `JsBigInt`.
+    ##
+    ## **Note:** On the native backends this returns an `Int128` from `nint128`.
+    runnableExamples:
+      echo ulid().toInt128()
+
+    result = big(ulid.timestamp) shl 80'big
+    result += ulid.randomness
+
+
+  proc fromInt128*(_: typedesc[ULID], val: JsBigInt): ULID =
+    ## Parses an `JsBigInt` to a `ULID`.
+    ##
+    ## **Note:** On the native backends this accepts an `Int128` from `nint128`
+    assert val <= HighInt128
+
+    result.timestamp = ((val and TimestampBitmask) shr 80'big).toNumber().int64
+    result.randomness = val and RandomnessBitmask
+
+
+when not defined(js):
+  func toBytes*(ulid: ULID): array[16, byte] =
+    ## Allows for a `ULID` to be converted to a byte array for the binary format.
+    ##
+    ## **Note:** This isn't available for the JS backend.
+    runnableExamples:
+      let
+        ulid = ULID.parse("01H999MBGTEA8BDS0M5AWEBB1A")
+        ulidBytes = [1.byte, 138, 82, 154, 46, 26, 114, 144, 182, 228, 20, 42, 184, 229, 172, 42]
+
+      assert ulid == ULID.fromBytes(ulidBytes)
+
+    when cpuEndian == littleEndian:
+      return cast[array[16, byte]](ulid.toInt128().swapBytes())
+
+    else:
+      return cast[array[16, byte]](ulid.toInt128())
+
+
+  func fromBytes*(_: typedesc[ULID], ulidBytes: openArray[byte]): ULID =
+    ## Parses a byte array to a `ULID.`.
+    ##
+    ## **Note:** This isn't available for the JS backend.
+
+    if ulidBytes.len != 16:
+      raise newException(RangeDefect, "Given byte array must be 16 bytes long!")
+
+    when cpuEndian == littleEndian:
+      return ULID.fromInt128(cast[Int128](ulidBytes.toArray(0..15)).swapBytes())
+
+    else:
+      return ULID.fromInt128(cast[Int128](ulidBytes.toArray(0..15)))
+
+
+func parse*(_: typedesc[ULID], ulidStr: string): ULID =
+  ## Parses a `ULID` from a string.
   runnableExamples:
-    echo nulidSync().toInt128()
+    echo ULID.parse("01H999MBGTEA8BDS0M5AWEBB1A")
-
-  result = i128(ulid.timestamp) shl 80
-
-  result.hi += cast[int64](ulid.randomness.hi)
-  result.lo += ulid.randomness.lo
-
-func fromInt128*(_: typedesc[NULID], val: Int128): NULID =
-  ## Parses an Int128 to a NULID.
-  result.timestamp = (val shr 16).hi
-  result.randomness = UInt128(
-    hi: cast[uint64]((val.hi shl 48) shr 48),
-    lo: val.lo
-  )
-
-func toBytes*(ulid: NULID): array[16, byte] =
-  ## Allows for a NULID to be converted to a byte array.
-  runnableExamples:
-    let
-      ulid = parseNulid("01H999MBGTEA8BDS0M5AWEBB1A")
-      ulidBytes = [1.byte, 138, 82, 154, 46, 26, 114, 144, 182, 228, 20, 42, 184, 229, 172, 42]
-
-    echo ulid == NULID.fromBytes(ulidBytes)
-
-  when cpuEndian == littleEndian:
-    return cast[array[16, byte]](ulid.toInt128().swapBytes())
-
-  else:
-    return cast[array[16, byte]](ulid.toInt128())
-
-func fromBytes*(_: typedesc[NULID], ulidBytes: openArray[byte]): NULID =
-  ## Parses a byte array to a NULID.
-  if ulidBytes.len != 16:
-    raise newException(RangeDefect, "Given byte array must be 16 bytes long!")
-
-  when cpuEndian == littleEndian:
-    return NULID.fromInt128(cast[Int128](ulidBytes.toArray(0..15)).swapBytes())
-
-  else:
-    return NULID.fromInt128(cast[Int128](ulidBytes.toArray(0..15)))
-
-func parseNulid*(ulidStr: string): NULID =
-  ## Parses a string to a NULID.
-  runnableExamples:
-    echo parseNulid("01H999MBGTEA8BDS0M5AWEBB1A")
 
   if ulidStr.len != 26:
     raise newException(RangeDefect, "Invalid ULID! Must be 26 characters long!")
 
   result.timestamp = int64.decode(ulidStr[0..9])
-  result.randomness = UInt128.decode(ulidStr[10..25])
+  when not defined(js):
+    result.randomness = UInt128.decode(ulidStr[10..25])
+  else:
+    result.randomness = JsBigInt.decode(ulidStr[10..25])
 
-func `$`*(ulid: NULID): string =
+
+proc `==`*(a, b: ULID): bool = a.toInt128() == b.toInt128()
+
+
+func `$`*(ulid: ULID): string =
   ## Returns the string representation of a ULID.
   runnableExamples:
-    echo nulidSync()
+    echo $ulid()
 
-  result = Int128.encode(ulid.toInt128(), 26)
+  when not defined(js):
+    result = Int128.encode(ulid.toInt128(), 26)
+  else:
+    result = JsBigInt.encode(ulid.toInt128(), 26)
+
+# std/json support
+proc `%`*(u: ULID): JsonNode =
+  ## Serializes a `ULID` to JSON.
+  newJString($u)
+
+proc to*(j: JsonNode, _: typedesc[ULID]): ULID =
+  ## Deserializes a `ULID` from JSON.
+  if j.kind != JString:
+    raise newException(JsonKindError, "Expected a string!")
+
+  result = ULID.parse(j.getStr())
+
+when HasJsony:
+  import jsony
+
+  proc dumpHook*(s: var string, ulid: ULID) = s.dumpHook($ulid)
+  proc parseHook*(s: string, i: var int, ulid: var ULID) =
+    var res: string
+    parseHook(s, i, res)
+    ulid = ULID.parse(res)
+
+when HasDebby:
+  import std/sequtils
+  import debby/common
+
+  func sqlDumpHook*(v: ULID): string = sqlDumpHook(cast[Bytes](v.toBytes().toSeq()))
+  func sqlParseHook*(data: string, v: var ULID) =
+    var res: Bytes
+    sqlParseHook(data, res)
+    v = ULID.fromBytes(cast[seq[byte]](res))

src/nulid/private/constants.nim

@@ -0,0 +1,44 @@
+const
+  LowInt48* = 0'i64
+  HighInt48* = 281474976710655'i64
+
+const
+  HighUint80Str = "1208925819614629174706176"
+  TimestampBitmaskStr = "340282366920937254537554992802593505280"
+  RandomnessBitmaskStr = "1208925819614629174706175"
+
+when not defined(js):
+  import nint128
+
+  const
+    LowUint80* = u128(0)
+    HighUint80* = u128(HighUint80Str)
+
+    #TimestampBitmask = big(TimestampBitmaskStr)
+    #RandomnessBitmask = big(RandomnessBitmaskStr)
+
+else:
+  import std/[
+    jsbigints
+  ]
+
+  let
+    LowUint80* = big(0)
+    HighUint80* = big(HighUint80Str)
+
+    HighInt128* = big("340282366920938463463374607431768211455")
+
+    TimestampBitmask* = big(TimestampBitmaskStr)
+    RandomnessBitmask* = big(RandomnessBitmaskStr)
+
+
+# No sysrand on the JS backend nor VM.
+const InsecureRandom* = defined(nulidInsecureRandom) or defined(nimscript)
+const NoLocks* = defined(nulidNoLocks) or defined(js) or defined(nimscript)
+
+# Support for other libraries
+{.warning[UnusedImport]:off.}
+const
+  HasJsony* = compiles do: import jsony
+
+  HasDebby* = compiles do: import debby/common

tests/test1.nim

@@ -4,36 +4,54 @@
 # the letter 't').
 #
 # To run these tests, simply execute `nimble test`.
+import std/[
+  unittest,
+  json
+]
 
-import unittest
+const UlidRandStr = "541019288874337045949482"
 
-import pkg/nint128
+when not defined(js):
+  import nint128
+
+  const UlidRand = u128(UlidRandStr)
+else:
+  import std/jsbigints
+
+  let UlidRand = big(UlidRandStr)
 
 import nulid
 
-let gen = initNulidGenerator()
+test "ULID Generation":
-
-test "NULID Generation":
   for _ in 0..5:
-    let nulid = gen.nulidSync()
+    let ulid = ulid()
-    echo nulid
+    echo ulid
 
-test "NULID Parsing":
+test "ULID Parsing":
-  let nulidStr = "01H999MBGTEA8BDS0M5AWEBB1A"
+  let ulidStr = "01H999MBGTEA8BDS0M5AWEBB1A"
-  let nulid = NULID(timestamp: 1693602950682,
+  let ulid = ULID(timestamp: 1693602950682,
-    randomness: u128("541019288874337045949482"))
+    randomness: UlidRand)
 
-  check parseNulid(nulidStr) == nulid
+  check ULID.parse(ulidStr) == ulid
 
-test "NULID Int128 Conversion":
+test "ULID Int128 Conversion":
-  let nulid = parseNulid("01H999MBGTEA8BDS0M5AWEBB1A")
+  let ulid = ULID.parse("01H999MBGTEA8BDS0M5AWEBB1A")
 
-  check NULID.fromInt128(nulid.toInt128()) == nulid
+  check ULID.fromInt128(ulid.toInt128()) == ulid
 
-test "NULID Binary Format":
+when not defined(js):
-  let
+  # Not planned to be implemented yet for the JS backend
-    nulid = parseNulid("01H999MBGTEA8BDS0M5AWEBB1A")
-    nulidBytes = [1.byte, 138, 82, 154, 46, 26, 114, 144, 182, 228, 20, 42, 184, 229, 172, 42]
 
-  check nulid == NULID.fromBytes(nulidBytes)
+  test "ULID Binary Format":
-  check nulid.toBytes == nulidBytes
+    let
+      ulid = ULID.parse("01H999MBGTEA8BDS0M5AWEBB1A")
+      ulidBytes = [1.byte, 138, 82, 154, 46, 26, 114, 144, 182, 228, 20, 42, 184, 229, 172, 42]
+
+    check ulid == ULID.fromBytes(ulidBytes)
+    check ulid.toBytes == ulidBytes
+
+test "ULID std/json support":
+  let ulid = ULID.parse("01H999MBGTEA8BDS0M5AWEBB1A")
+
+  check (%ulid).getStr() == "01H999MBGTEA8BDS0M5AWEBB1A"
+  check (%ulid).to(ULID) == ulid