OpString is a JavaScript module for mapping and executing operations represented by character sequences.
OpString simplifies the process of mapping characters to operations and values, and provides functionality to compose character sequences and execute the respective mapped operations.
OpString is particularly useful in scenarios where data saving is crucial. By representing operations using compact character sequences, OpString enables you to pack more functionality into less data, optimizing storage efficiency.
For example, let's say you have the operations circle(30, 30, 20) and rect(30, 20, 55, 55) that you would like to store as a string for later use. Your string could look something like this circle(30,30,20);rect(30,20,55,55) and would be 34 characters long. With OpString you could represent the same operations with the character sequence AaabBabcc, which would shorten it to 9 characters.
Install OpString using npm:
npm install opstringImport OpString into your project using the import statement.
import OpString from 'opstring';Download the latest version from Releases.
Import OpString into your project using the import statement, referencing opstring.js.
// app.js
import OpString from 'opstring.js';Make sure that the <script> tag, which embeds the JavaScript file containing the import of OpString, has the attribute type="module".
<script src="app.js" type="module"></script>When using OpString, there are mainly three steps involved:
- Register operations and values
- Compose character sequence
- Execute character sequence
OpString provides flexibility in managing these steps. Below, you will find two approaches for using OpString, which can be combined as needed.
With this approach, you register operations and values, and specify the character sequence when creating the OpString instance.
// Create a new instance and configure it with initial settings
const opString = new OpString({
sequence: 'AaabBabcc',
operations: {
'A': (x, y, d) => { console.log(x, y, d); },
'B': (x, y, w, h) => { console.log(x, y, w, h); },
},
values: {
'a': 30,
'b': 20,
'c': 55,
},
labels: {
'circle': 'A',
'rect': 'B',
},
maxSequenceLength: 10,
ignoreWarnings: false, // (default: false)
strictMode: true, // (default: false)
});
// Execute the sequence 'AaabBabcc'
opString.execute();
// Execute a custom sequence
opString.execute('Babcc');Note: The properties ignoreWarnings and strictMode can only be configured when creating an OpString instance. (see Error Handling)
With this approach, you start with an empty OpString instance and register operations and values as needed. Then, you compose the character sequence by appending, inserting, prepending and removing operations and their corresponding values.
// Create an empty OpString instance
const opString = new OpString();
// Set the maximum sequence length
opString.setMaxSequenceLength(10);
// Register operations
opString.registerOperation('A', (x, y, d) => { console.log(x, y, d); });
opString.registerOperation('B', (x, y, w, h) => { console.log(x, y, w, h); });
// Alternatives: `registerOperations` and `setOperations`
// Register values
opString.registerValue('a', 30);
opString.registerValue('b', 20);
opString.registerValue('c', 55);
// Alternatives: `registerValues` and `setValues`
// Register labels
opString.registerLabel('circle', 'A');
opString.registerLabel('twenty', 'b');
// Alternatives: `registerLabels` and `setLabels`
// Get symbols for values
const char = opString.getCharForValue(55); // Returns: 'c'
const charCode = opString.getCharCodeForValue(55); // Returns: 99
// Get symbols for labels
const labelChar = opString.getCharForLabel('circle'); // Returns: 'A'
const labelCharCode = opString.getCharCodeForLabel('circle'); // Returns: 65
// Compose the character sequence
opString.append('A', ['a', 'a', 'b']);
opString.append('B', ['a', 'b', 'c', 'c']);
// Alternative: `setSequence`
// Insert an operation at a specific position
const operationId = opString.insert(1, 'X', ['x', 'y', 'z']);
console.debug(opString.getSequence());
// Expected output: 'AaabXxyzBabcc'
// Remove an operation by its id
opString.remove(operationId);
console.debug(opString.getSequence());
// Expected output: 'AaabBabcc'
// Execute the composed sequence
opString.execute();
// Execute a custom sequence
opString.execute('Babcc');OpString aims to handle errors gracefully, providing warnings without interrupting its functionality.
To ignore warnings, you can set ignoreWarnings to true when creating an OpString instance. When ignoreWarnings is true and errors occur, warnings will not be logged to the console.
// Create an OpString instance and ignore warnings
const opString = new OpString({
ignoreWarnings: true, // (default: false)
});To enable strictMode, you can set strictMode to true when creating an OpString instance.
In strictMode OpString will log errors instead of warnings to the console. Furthermore, OpString will not be as graceful anymore and certain functionalities like setSequence or execute will not work when errors occur, such as exceeding the maxSequenceLength limit.
// Create an OpString instance with `strictMode` enabled
const opString = new OpString({
strictMode: true, // (default: false)
});Note: In strictMode the ignoreWarnings property is irrelevant as warnings are never logged.
Note: OpString is still in the initial development phase and the API can still change. Always review the release notes.
OpString exposes the following properties and methods:
version
A string representing the version of OpString.
// Access the version of OpString
console.log(opString.version);
// Output: '0.5.1'constructor(config?)
Creates an instance of OpString.
// Create an empty OpString instance
const opString = new OpString();
// Create an OpString instance and enable `strictMode`
const opString = new OpString({
strictMode: true, // (default: false)
});
// Create a new instance and configure it with initial settings
const opString = new OpString({
sequence: 'AaabBabcc',
operations: {
'A': (x, y, d) => { console.log(x, y, d); },
'B': (x, y, w, h) => { console.log(x, y, w, h); },
},
values: {
'a': 30,
'b': 20,
'c': 55,
},
labels: {
'circle': 'A',
'rect': 'B',
},
maxSequenceLength: 10,
ignoreWarnings: false, // (default: false)
strictMode: true, // (default: false)
});| Parameter | Type | Description |
|---|---|---|
config? |
Object |
(Optional) Config object to configure OpString features. |
config.sequence? |
string |
(Optional) The character sequence to be executed when execute is called without providing a sequence parameter. (default: '') |
config.operations? |
Object |
(Optional) Object containing the operation mappings to be registered. (default: {}) |
config.values? |
string |
(Optional) Object containing the value mappings to be registered. (default: {}) |
config.labels? |
string |
(Optional) Object containing the label mappings to be registered. (default: {}) |
config.maxSequenceLength? |
string |
(Optional) Specifies a maximum allowed sequence length. If defined, it must be a positive safe integer. (default: undefined) |
config.ignoreWarnings? |
string |
(Optional) Specifies whether warnings should be ignored. (default: false) |
config.strictMode? |
string |
(Optional) Specifies the behavior of the OpString with regard to errors. If set to true, errors will be logged; otherwise, warnings will be logged. Furthermore, if set to true the maxSequenceLength must strictly be adhered to, otherwise, the respective character sequence will not be set/executed. (default: false) |
getNextId()
Returns the id to be assigned to the next appended operation.
// Get the next operation id
const nextId = opString.getNextId();
// Example output: 3number - The next operation id
append(operation, values?)
Appends an operation to the sequence and returns the id of the appended operation.
// Append an operation to the sequence and return its id
const operationId = opString.append('V');
// Specify the values to be passed to the operation. This will append 'Aaab' to the sequence.
opString.append('A', ['a', 'a', 'b']);
/**
* Alternatively, you can use character codes instead of characters (e.g. 'A'.charCodeAt(0) => 65).
* This will also append 'Aaab' to the sequence.
*/
opString.append(65, [97, 97, 98]);| Parameter | Type | Description |
|---|---|---|
operation |
string|number |
The character code of the operation to be appended. |
values? |
Array<string|number> |
(Optional) An array with the character codes of the values corresponding to the operation to be appended. |
number|boolean - The id of the appended operation or false if the operation wasn't appended.
insert(index, operation, values?)
Inserts an operation to the sequence at the specified index and returns the id of the inserted operation.
/**
* Insert an operation at index 2 of the operations to be executed and returns
* its id. The operation will be the third one to be executed.
*/
const operationId = opString.insert(2, 'V');
/**
* Specify the values to be passed to the operation.
*
* The following example inserts the operation 'Aaab' at index 2 of the
* operations to be executed, making it the third operation to be executed.
*/
opString.insert(2, 'A', ['a', 'a', 'b']);
/**
* Alternatively, you can use character codes instead of characters (e.g. 'A'.charCodeAt(0) => 65).
* This will also insert 'Aaab' at index 2 of the sequence.
*/
opString.insert(2, 65, [97, 97, 98]);| Parameter | Type | Description |
|---|---|---|
index |
number |
The index at which the operation should be added. |
operation |
string|number |
The character code of the operation to be appended. |
values? |
Array<string|number> |
(Optional) An array with the character codes of the values corresponding to the operation to be appended. |
number|boolean - The id of the inserted operation or false if the operation wasn't inserted.
prepend(operation, values?)
Prepends an operation to the sequence and returns its id.
// Prepend an operation to the sequence and return its id
const operationId = opString.prepend('V');
// Specify the values to be passed to the operation. This will prepend 'Aaab' to the sequence.
opString.prepend('A', ['a', 'a', 'b']);
/**
* Alternatively, you can use character codes instead of characters (e.g. 'A'.charCodeAt(0) => 65).
* This will also prepend 'Aaab' to the sequence.
*/
opString.prepend(65, [97, 97, 98]);| Parameter | Type | Description |
|---|---|---|
operation |
string|number |
The character or character code of the operation to be prepended. |
values? |
Array<string|number> |
(Optional) An array with the characters or character codes of the values corresponding to the operation to be prepended. |
number|boolean - The id of the prepended operation or false if the operation wasn't prepended.
remove(id)
Removes the operation with the specified id from the sequence.
// Remove operation with id 3 from the sequence
const removed = opString.remove(3);| Parameter | Type | Description |
|---|---|---|
id |
number |
The id of the operation that should be removed. |
boolean - If the respective operation was removed true, otherwise false.
index(id)
Returns the index of the operation with the provided id in the sequence.
// Get the index of operation with id 3 in the sequence
const operationIndex = opString.index(3);| Parameter | Type | Description |
|---|---|---|
id |
number |
The id of the operation in the sequence for which the index should be returned. |
number|undefined - Index of the operation in the sequence, or undefined if not found.
setSequence(sequence)
Sets the character sequence.
// Set the character sequence
opString.setSequence('AaabBabcc');
/**
* Handling an unknown value character
*
* Suppose the sequence is 'Ba?c'. The '?' represents an unknown value character.
* In this case, the unknown character will be registered with a value of `null`.
* By registering it this way, the associated operation can still be executed.
*/
opString.setSequence('Ba?c');| Parameter | Type | Description |
|---|---|---|
sequence |
string |
The character sequence that should be set. |
getSequence()
Returns the character sequence.
// Get the character sequence
const sequence = opString.getSequence();
// Example output: 'AaabBabcc'string - The character sequence.
getSequenceData()
Returns the sequence data array.
// Get the sequence data array
const sequenceData = opString.getSequenceData();
// Example output for sequence 'AaabBabcc':
// [
// { id: 1, operation: 65, values: [ 97, 97, 98 ] },
// { id: 2, operation: 66, values: [ 97, 98, 99, 99 ] }
// ]Array<Object> - The sequence data array
registerOperation(symbol, callback)
Registers an operation mapping.
// Register an operation mapping
opString.registerOperation('X', () => console.log('Operation X'));
// Register an operation mapping using character code
opString.registerOperation(88, () => console.log('Operation X'));| Parameter | Type | Description |
|---|---|---|
symbol |
`string | number` |
callback |
function |
The function to which the symbol should be mapped. |
registerOperations(operations)
Registers additional operation mappings provided by the `operations` object.
// Register additional operation mappings
opString.registerOperations({
'D': () => { /*...*/ },
'E': () => { /*...*/ },
'F': () => { /*...*/ },
});
// Register additional operation mappings using chracter codes
opString.registerOperations({
68: () => { /*...*/ },
69: () => { /*...*/ },
70: () => { /*...*/ },
});| Parameter | Type | Description |
|---|---|---|
operations |
Object |
Object containing additional operation mappings to be registered. |
setOperations(operations)
Registers the operation mappings provided by the `operations` object. Previously registered operation mappings will be deleted.
// Set new operation mappings
opString.setOperations({
'A': () => { /*...*/ },
'B': () => { /*...*/ },
'C': () => { /*...*/ },
});| Parameter | Type | Description |
|---|---|---|
operations |
Object |
Object containing new operation mappings to be registered. |
getOperations()
Returns the registered operations.
// Get the registered operations
const operations = opString.getOperations();
// Example output:
// { '65': [Function: A], '66': [Function: B] }Object - The registered operations
registerValue(symbol, value)
Registers a value mapping.
// Register a value mapping
opString.registerValue('x', 10);
// Register a value mapping using character code
opString.registerValue(120, 10);| Parameter | Type | Description |
|---|---|---|
symbol |
`string | number` |
value |
* |
The value to which the symbol should be mapped. |
registerValues(values)
Registers additional value mappings provided by the `values` object.
// Register additional value mappings
opString.registerValues({
'x': 10,
'y': 11,
'z': 12,
});
// Alternatively, you can register additional value mappings using character codes
opString.registerValues({
120: 10,
121: 11,
122: 12,
});| Parameter | Type | Description |
|---|---|---|
values |
Object |
Object containing additional value mappings to be registered. |
setValues(values)
Registers the value mappings provided by the `values` object. Previously registered value mappings will be deleted.
// Set new value mappings
opString.setValues({
'a': 1,
'b': 2,
'c': 3,
});
// Alternatively, you can set new value mappings using character codes
opString.setValues({
97: 1,
98: 2,
99: 3,
});| Parameter | Type | Description |
|---|---|---|
values |
Object |
Object containing new value mappings to be registered. |
getValues()
Returns the registered values.
// Get the registered values
const values = opString.getValues();
// Example output:
// { '97': 30, '98': 20, '99': 55 }Object - The registered values.
getCharForValue(value)
Returns the corresponding character for the provided value, if the value is registered.
// Get the corresponding character for the provided value
const char = opString.getCharCodeForValue(55);
// Example output: 'c'| Parameter | Type | Description |
|---|---|---|
value |
* |
The value for which a coresponding character should be returned. |
string|undefined - If the value is registered, the corresponding character is returned; otherwise undefined.
getCharCodeForValue(value)
Returns the corresponding character code for the provided value, if the value is registered.
// Get the corresponding charCode for the provided value
const charCode = opString.getCharCodeForValue(55);
// Example output: 99| Parameter | Type | Description |
|---|---|---|
value |
* |
The value for which a coresponding character code should be returned. |
number|undefined - If the value is registered, the corresponding character code is returned; otherwise undefined.
registerLabel(label, symbol)
Registers a label mapping to represent the provided symbol.
// Register a label mapping
opString.registerLabel('circle', 'A');
// Register a label mapping using character code
opString.registerLabel('circle', 65);| Parameter | Type | Description |
|---|---|---|
label |
string |
The label to represent the provided symbol. |
symbol |
string|number |
The character or character code to be mapped to the label. |
registerLabels(labels)
Registers additional label mappings provided by the `labels` object.
// Register additional label mappings
opString.registerLabels({
'circle': 'A',
'rect': 'B',
'ten': 'x',
});
// Alternatively, you can register additional label mappings using character codes
opString.registerLabels({
'circle': 65,
'rect': 66,
'ten': 120,
});| Parameter | Type | Description |
|---|---|---|
labels |
Object |
Object containing additional label mappings to be registered. |
setLabels(labels)
Registers the label mappings provided by the `labels` object. Previously registered label mappings will be deleted.
// Set new label mappings
opString.setLabels({
'circle': 'A',
'rect': 'B',
'ten': 'x',
});
// Alternatively, you can set new label mappings using character codes
opString.setLabels({
'circle': 65,
'rect': 66,
'ten': 120,
});| Parameter | Type | Description |
|---|---|---|
labels |
Object |
Object containing new label mappings to be registered. |
getLabels()
Returns the registered labels.
// Get the registered labels
const labels = opString.getLabels();
// Example output:
// { 'circle': 65, 'rect': 66, 'ten': 120 }Object - The registered labels.
getCharForLabel(label)
Returns the corresponding character for the provided label, if the label is registered.
// Get the corresponding character for the provided label
const char = opString.getCharCodeForLabel('circle');
// Example output: 'A'| Parameter | Type | Description |
|---|---|---|
label |
string |
The label for which a coresponding character should be returned. |
string|undefined - If the label is registered, the corresponding character is returned; otherwise undefined.
getCharCodeForLabel(label)
Returns the corresponding character code for the provided label, if the label is registered.
// Get the corresponding charCode for the provided label
const charCode = opString.getCharCodeForLabel('circle');
// Example output: 65| Parameter | Type | Description |
|---|---|---|
label |
string |
The label for which a coresponding character code should be returned. |
number|undefined - If the label is registered, the corresponding character code is returned; otherwise undefined.
setMaxSequenceLength(maxSequenceLength)
Sets the maximum allowed sequence limit.
// Set the maximum sequence length to 100
opString.setMaxSequenceLength(100);| Parameter | Type | Description |
|---|---|---|
maxSequenceLength |
number |
The maximum allowed sequence length. |
getMaxSequenceLength()
Returns the configured `maxSequenceLength` value. If the `maxSequenceLength` has not been configured, `undefined` is returned.
// Get the max sequence length
const maxSequenceLength = opString.getMaxSequenceLength();
// Example output, if configured: 100
// Output, if not configured: undefinednumber|undefined - The configured maxSequenceLength value, or undefined if not configured.
execute(sequence?)
Attempts to execute the character sequence of the current instance or a provided character sequence specified by the `sequence` parameter.
// Execute the character sequence of the current instance
opString.execute();
// Execute a provided character sequence
opString.execute('XxxyYxyzz');| Parameter | Type | Description |
|---|---|---|
sequence |
string |
(Optional) The character sequence to be executed instead of the character sequence of the current instance. |
Are you considering contributing to OpString? Check out our contributing guidelines.
OpString is MIT licensed.