@iwatakeshi/sakura

A unit of a data structure to build elegant trees or cherry blossoms 🌸

Usage no npm install needed!

<script type="module">
  import iwatakeshiSakura from 'https://cdn.skypack.dev/@iwatakeshi/sakura';
</script>

README

sakura

A unit of a data structure to build elegant trees or cherry blossoms 🌸

Node CI Codecov Version Downloads/week License

About

Sakura has an elegant Node class that wraps some of the familiar APIs we use for arrays. However, instead of arrays, we're dealing with nodes.

Here's an example:

import { Node } from '@iwatakeshi/sakura'
// Note: If you use require(), then it's:
// const { Node } = require('@iwatakeshi/sakura')

// Let's make a root node and give it a name
// of 'a' and an id of '1'
const a = new Node('1', 'a', true)

// Let's create two other leaf nodes
const b = new Node('2', 'b')
const c = new Node('3', 'c')

// Add 'b' as a child of 'a'
a.push(b)
// Add 'c' as a child of 'b'
b.push(c)

// Let's search for 'c'!
console.log(a.search('3'))
// => 
// Node {
//   isRoot: false,
//   name: 'c',
//   id: '567',
//   children: [],
//   _parent: Node {
//     ...
//   }
// }

But wait, there's more!

What if we wanted to get the index or the depth of a child node?

// continued...

const d = new Node('4', 'd')
const e = new Node('5', 'e')

b.push(d)
b.push(e)
const result = a.search('5')
console.log(result.index)
// => 2
console.log(result.depth)
// => 2

Of course, we can have some fun by manipulating some children:

// continued...

const f = new Node('6', 'f')
const g = new Node('7', 'g')

e.push(f)
e.push(g)

console.log(
  a.search('2')
   .find(node => node!.id === '5')
   .map(node => node!.data)
 )
// => ['f', 'g']

By now, I think you get the idea...

API

Node

class Node<T = any> {

  /**
   * The Node constructor
   * @param name A label for the node.
   * @param isRoot Sets the node as the root.
   * @param id A unique identifier for the node.
   */
  constructor(id: string, data?: T, isRoot = false)

  /**
   * Appends a child to the node, and returns the new length of the node's children.
   * @param child The child node to append.
   */
  push(child: Node): number;
  
  /**
   * Removes the last child of the node and returns it.
   */
  pop(): Maybe<Node>;

  /**
   * Inserts a new child at the start the node's children.
   * @param child The child to insert.
   */
  unshift(child: Node): number;

  /**
   * Removes the first child from the node and returns it.
   */
  shift(): Maybe<Node>;

  /**
   * Removes a child from the node.
   * @param child The child node to remove.
   */
  remove(child: Node): Maybe<Node>[];

  /**
   * Removes a child from the node.
   * @param index The index of the child to remove.
   */
  removeAt(index: number): Maybe<Node>[];

  /**
   * Returns the children of the node that meet the condition specified in a callback function.
   * @param cb A function that accepts up to three arguments.
   * The filter method calls the callback function one time for each * child of the node.
   */
  filter(cb: (node: Maybe<Node>, index?: number, nodes?: Maybe<Node>[]) => boolean): Maybe<Node>[];

  /**
   * Calls a defined callback function on each child of the node,
   * and returns an array that contains the results.
   * @param cb A function that accepts up to three arguments.
   * The map method calls the cb function one time for each child of the node.
   */
  map<T>(cb: (node: Maybe<Node>, index?: number, nodes?: Maybe<Node>[]) => T): T[];

  /**
   * Returns the value of the first child of the node where predicate is true, and undefined otherwise.
   * @param predicate  find calls predicate once for each child of the node, in ascending order,
   * until it finds one where predicate returns true. If such a child is found,
   * find immediately returns that child. Otherwise, find returns undefined.
   */
  find(predicate: (node: Maybe<Node>, index?: number, nodes?: Maybe<Node>[]) => boolean): Maybe<Node>;

  /**
   * Returns the index of the first child of the node where predicate is true, and -1 otherwise.
   * @param predicate find calls predicate once for each child of the node, in ascending order,
   * until it finds one where predicate returns true. If such a child is found,
   * findIndex immediately returns that child index. Otherwise, findIndex returns -1.
   */
  findIndex(predicate: (node: Maybe<Node>, index?: number, nodes?: Maybe<Node>[]) => boolean): number;

  /**
   * Returns the index of the first occurrence of a value in the node's children.
   * @param child The child node to locate.
   */
  indexOf(child: Node): number;

  /**
   * Determines whether the node includes a certain child, returning true or false as appropriate.
   * @param child The child to search for.
   * @param fromIndex The position in this node's children at which to begin searching for the child.
   */
  includes(child: Node, fromIndex?: number): boolean;

  /**
   * Serializes the node into a JSON friendly format.
   */
  serialize(): NodeSchema;

  /**
   * Deserializes a JSON friendly format into a Node.
   * @param schema The serialized node schema.
   */

  deserialize(schema: NodeSchema);
  /**
   * Deeply searches for a child node.
   *
   * Note: Search starts from the current node.
   * @param id The id of the node to search for.
   */
  search(id: string): Maybe<Node>;


  /**
   * Returns the index of the node's position relative to the node's parent.
   *
   * Note: Be sure to check if the node has a parent.
   */
  get index(): number;

  /**
   * The parent of the node.
   */
  get parent(): Maybe<Node>;

  /**
   * Determines whether the node has children.
   */
  get isParent(): boolean;

  /**
   * Deeply searches for a child node.
   *
   * Note: Search performs a breadth-first search.
   * @param node The root node to search from.
   * @param id The id of the node to search for.
   */
  static search(node: Node, id: string): Maybe<Node>

  /**
   * Deserializes a JSON friendly format into a Node.
   * @param schema The serialized node schema.
   */
  static deserialize(schema: NodeSchema): Node
}

NodeSchema

interface NodeSchema<T = any> {
  id: string
  data?: T
  children: NodeSchema[]
  isRoot: boolean
  isParent: boolean
  index: number
  depth: number
}