DoKit

DoKit - A modern Javascript library for getting tasks done quickly and easily.

Table Of Contents

• Overview
• Dictionary
• Hidden Values
• Reactivity
• DoKit strings

Overview

DoKit is a library that simplifies common or complex tasks in your project. It serves as a building block rather than a framework, meaning it complements your project rather than being the main driver of it. You can use DoKit to implement specific features, but it is not intended to handle all aspects of your project. It is meant to be used alongside other libraries to enhance your development experience. While DoKit can be helpful, it is not intended as a one-stop solution for all your development needs. Wow, that was a big wall of text.

DoKit Dictionary

So-, as you know, Javascript has objects, right? Well, those are great and all, but a little clunky. Let me explain.

// Javascript
const obj = {foo:"bar"};
Object.keys(obj); // [foo]
Object.values(obj) // [bar]

// doKit
import dk from "dokit";
const dict = new dk.Dict({foo:"bar"});
dict.keys // [foo]
dict.values // [bar]

Same result, but much cleaner.

DoKit's dictionaries have many methods and properties like that.

Setting a value

const dict = new dk.Dict();
dict.set("key", "value");  // Also adds values

Setting it with options

const dict = new dk.Dict();
dict.add("key", "value", options); // Also sets the value

Options

In a doKit dictionary, there are many ways to modify the behavior. For example, you can set options on the entire dictionary, like so:

const dict = new Dict({/* Put keys and values here */}, options);

Here's the typescript interface for entire dictionary options:

interface dictOptions {
    /** Allows `dict.hasHiddenItems` to be read. If true, will return true if any items are hidden. If false, will return false. @default `true` @see `dictOptions.throwErrorWhenCheckingHiddenItems` */
    allowCheckingForHiddenItems?:boolean
    /** Requires `allowCheckingHiddenItems` to be false. If true, will throw an error when `dict.hasHiddenItems` is read. If false, and the former is true, null is returned. @default `false` */
    throwErrorWhenCheckingHiddenItems?:boolean
    /** Wether to allow `forEach` to read hidden items. @default `true`*/
    allowLoopingOverHiddenItems?:boolean
    /** Wether to allow `filter` to read hidden items. @default `true` */
    allowFilteringHiddenItems?:boolean
    /** Wether to allow `map` to read and set hidden items @default `true` */
    allowMappingHiddenItems?:boolean
}

Okay, but this is currently just a glorified object, right? Well, you'd be mostly correct, except, as well as object wide options, each value can have options too. Here's how you set them, again

const dict = new dk.Dict();
dict.add("key", "value", options);
// Or
dict.setOptions("key", options);

Here's the typescript interface for value options:

interface DictValueOptions {
    /** Default value */
    default?:any,
    /** Wether key is readonly Default:false */
    readonly?:boolean,
    /** Wether to delete after read, default:false */
    burn?:boolean,
    /** Wether to freeze options, default:false  */
    freezeOptions?:boolean,
    /** Wether or not to not return value/key when `items`, `keys`, or `forEach` is called. Requires some permissions on the dictionary to be set in advance.  */
    hidden?:boolean
}

Okay, we've covered the basics of options.

Deleting Values

In a doKit dictionary, you can delete values like so:

const dict = new dk.Dict({foo:"bar"});
dict.delete("foo");
// Or
dict.del("foo");

Getting a list of values

Use Dictionary.values. This turns hidden items to undefined. If this behavior is undesirable, use Dictionary.items, where hidden items are not returned at all.

const dict = new dk.Dict({foo:"bar"});
dict.values // [bar]

Getting a list of keys

Similar to values, use Dictionary.keys. This ignores hidden keys.

const dict = // dict from before
dict.keys // [foo]

Getting a specific item

Use Dictionary.item. This can retrieve hidden values.

const dict = // dict from before
dict.item("foo") // "bar"

Looping over each item in the dictionary

You could use a for...in or a for...of loop, but doKit provides a forEach method Similar to Array.forEach, you use it almost the same

dict.forEach((key, value, index)=>{
    // do something
    // Note, index is the index of the key. Don't know why you'd use it, but you can.
});

There are a bunch of other methods like filter and such, but this is quite long already.

Hidden Values

In DoKit, you can create hidden values by using the Hidden class. These values are only accessible to things that you want to have access (and of course, doKit). Here's an example

const hidden = dk.Hidden.from("value", {
    accessControl(key:any, action:"read"|"write"){
        return false; // Prevent anything but doKit itself from reading the value (outside code cannot read the value, only the doKit script itself)
    }
});
// You can't access the value.

For a more realistic example, here's how you could actually use this:

// Make this value readonly in real JS, not just Typescript.
const hidden = dk.Hidden.from("value", {
    accessControl(key:any, action:"read"|"write") {
        return action==="read";
    }
});
// Then, to get the value
dk.Hidden.getValue(hidden, "key"); // "value"
// But when writing to the value, you cannot.
dk.Hidden.setValue(hidden, "newValue", "key");

Reactivity

In doKit there are two ways to define reactive values, with Store and the @reactive decorator. The latter you can find in Decorators With the store object, you subscribe to changes, and when the value changes, the subscriber is notified.

Creating a Store

Create one like so:

import {Store} from "dokit" // or dk.Store
const store = new Store(value);

Accessing the value

Access the value with value

store.value // The value of the store

Setting the vale

Just assign to value

store.value = "new value"

Now, subscribers will be notified

Using multiple data types (Typescript)

If your store can contain many types of data, declare it like a typescript generic.

const store:Store<string|number> = new Store("value");

Now, when doing this, even as the store is storing a string, you can assign a number.

store.value = 100;

Subscribing to the store

store.subscribe((oldValue,newValue)=>{
    // do something
});

When the value, you get the old and new value.

Unsubscribing from the store

The subscribe method returns a function, and when called, it unsubscribes from the store.

const unsubscribe = store.subscribe((oldValue,newValue)=>{

});
// Unsubscribe
unsubscribe(); // Now, the the callback is no longer triggered on changes.

That's about it for stores.

DoKit Strings

In DoKit, you have a dkString which is like a string, except with more methods.

Creating a DoKit string

Either create a new object, or use the from method.

const str = new dkString("regular Javascript string");
// Or
const str = dkString.from("regular Javascript string");

Okay, but what if a function or something needs a PJS (Plain Javascript String)? Well, just use string.str to get the PJS.

const str = dkString.fom("regular Javascript string")
str.str // regular Javascript string

Now, you can use DoKit strings in your apps.

Now, you can use DoKit's strings in your code. DoKit strings have many methods to make things easier

Naming

DoKit's methods for naming are simple. Make it as close to English as possible. For example:

// Convert celsius to fahrenheit, it reads like english.
import {Convert} from "dokit";
Convert.celsiusToFahrenheit(0) // 32

You can read it like an english sentence. Its function is clear: Convert 0 degrees celsius to fahrenheit.

Please note, this readme is just the start of what doKit can do. Use your IDE to see more details, but for convince, as of v0.0.1, this is all the things doKit exports:

• Dictionary,
• Dict (alias for Dictionary),
• Store,
• String (alias for dkString),
• dkString,
• Number (alias for dkNumber),
• dkNumber,
• Array (alias for dkArray),
• Convert,
• Stack,
• Tuple,
• Misc,
• Hidden,
• Decorators