Constructing keys

The @ibnlanre/builder package provides a mechanism for constructing keys using the builder object. This process is aided by the $use and $get methods, which are available at every level of the builder object.

These methods are designed to access the register's values, as well as, generate keys from the register's nodes. While they perform similar operations, there is a subtle difference. The $use method adheres to the pattern defined by the node's value, whereas the $get method does not.

The following code snippet shows the sample builder that would be used in this guide:

const register = {
  foo: {
    baz: (id: number) => `/bazaar/${id}`,
    bar: 10,
  },
};
 
const builder = createBuilder(register, { prefix: ["root"] });

Uniform signature

The $use method is used to retrieve the keys, expecting the same signature as the defined value. If the value of that node is a primitive value, object or array, the $use method expects no arguments. However, if the value is a function that expects arguments, the $use method expects the same arguments.

foo.baz is a function that expects an id of number type, therefore, the $use method expects an id of number type as well. If the argument was optional, it would equally be optional. Likewise, if the value is a function that no arguments, the $use method would not expect any arguments.

The following code snippet demonstrates how to use the $use method:

// Invoking the `$use` method without any arguments
builder.foo.$use(); // ["root", "foo"]
 
// Invoking the `$use` method with required arguments
builder.foo.baz.$use(11); // ["root", "foo", "baz", 11]

Variable signature

The $get method is used to retrieve the keys, without following the pattern defined by the value. It expects an arbitrary number of arguments, which are added to the returned key. This flexibility exhibited by the $get method is particularly useful when you want to add more keys to the returned array of strings. The arguments can be of any type, and they are added to the returned key in the order they are passed.

The following code snippet demonstrates how to retrieve nested node keys:

// Invoking the `$get` method without any arguments
builder.foo.baz.$get(); // ["root", "foo", "baz"]
 
// Invoking the `$get` method with a string argument
builder.foo.baz.$get("test"); // ["root", "foo", "baz", "test"]
 
// Invoking the `$get` method with multiple arguments
builder.foo.baz.$get("test", { id: 11 }); // ["root", "foo", "baz", "test", { id: 11 }]

String as keys

The $get method on the root node of the builder object is unique in that if it is called without an argument, it returns the prefixes used to create the builder object. However, it can also accept a string as an argument, which becomes the key returned by the method. This behavior is distinct from other nodes, which appends the string argument to the returned key.

The $get method is typed to suggest the possible keys that can be passed to it, based on the structure of the register. The following code snippet demonstrates how to create a key using a string argument:

// Invoking the `$get` method without any arguments
builder.$get(); // ["root"]
 
// Invoking the `$get` method with a string argument
builder.$get("root.foo"); // "root.foo"
 
// Invoking the `$get` method with multiple string arguments
builder.$get("root.foo", "baz"); // "root.foo.baz"