drago

Random sinogram generator for TypeScript

🫖drago is a web assembly for 🦋TypeScript, written in 🦀Rust, at the top of a technological stack which includes chinese-format, chinese-rand and other crates; the name of this project stems from the Italian word describing one of the fabled, 🌺sublime 🫖dragons of the Eastern legends.

Its purpose is simple and elegant: generating random Chinese logograms via LogogramGenerator class - in accordance with the parameters provided by the user as a variety of thematic categories.

Installation

TypeScript

The package on NPM is:

@giancosta86/drago

The public API entirely resides in the root package index, so you shouldn't reference specific modules.

Usage

The purpose of this library is to create random Chinese logograms on demand - which can be achieved via a sequence of minimalist steps:

1. Import the required identifiers:

   import initDrago, {
     LogogramGenerator,
     RandomParams,
   } from "@giancosta86/drago";

2. Initialize the web assembly; in any initialization block of your client, call:

   await initDrago(/*[optional module/path/URL here]*/);

   • Note 1: for synchronous initialization, the initSync function is available as a named import.

   • Note 2: most often, you'll' want to pass a parameter related to the location of your .wasm file.

3. Create an instance of LogogramGenerator - by calling its create static method and passing an object implementing the RandomParams interface. For example:

   const logogramGenerator = LogogramGenerator.create({
     seed: 90,
     variant: "Simplified",
     fraction: {
       denominatorRange: [1, 7],
       numeratorRange: [4, 21],
     },
     decimal: {
       integerRange: [1, 42],
       fractionalLengthRange: [1, 3],
     },
   });

   Later, you can store the instance and use it wherever you need.

   Note 1: most of the fields are optional - but at least one of the optional fields must be present; this constraint is due to the fact that LogogramGenerator requires at least one generation strategy.

   Note 2: anyway, in case of unacceptable settings, the create method will throw an object of type RandomParamsError, containing a detailed description.

   Note 3: because of limitations in the underlying implementation, you cannot have two or more independent LogogramGenerator instances: creating each instance automatically resets - to the latest value - the seed of the internal randomization engine, from which every single instance would draw its random data.

   In summary: you should have just one instance of LogogramGenerator in your client.

4. Call logograms() whenever you need to create random logograms: the generator will randomly pick one of the provided strategies, returning the Chinese characters as a string:

   let characters: string = logogramGenerator.logograms();

   Note: the generation of characters is a safe operations - because all the validations occur when instantiating LogogramGenerator.

See also

• chinese-format

• chinese-rand

• dyn-error

• digit-sequence