{"id":16758489,"url":"https://github.com/kessler/node-hstacks","last_synced_at":"2025-03-16T08:20:54.740Z","repository":{"id":142618771,"uuid":"47257313","full_name":"kessler/node-hstacks","owner":"kessler","description":"Build hierarchies of stacks of middlewares","archived":false,"fork":false,"pushed_at":"2015-12-02T16:56:58.000Z","size":19,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-08T08:12:40.411Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kessler.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-02T11:41:12.000Z","updated_at":"2021-03-31T18:52:13.000Z","dependencies_parsed_at":"2023-05-24T05:30:56.360Z","dependency_job_id":null,"html_url":"https://github.com/kessler/node-hstacks","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-hstacks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-hstacks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-hstacks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-hstacks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kessler","download_url":"https://codeload.github.com/kessler/node-hstacks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243842102,"owners_count":20356608,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T04:05:30.258Z","updated_at":"2025-03-16T08:20:54.713Z","avatar_url":"https://github.com/kessler.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hstacks [![npm status](http://img.shields.io/npm/v/hstacks.svg?style=flat-square)](https://www.npmjs.org/package/hstacks) \n\n**Hierarchical stacks** takes the middleware concept and expand it to a hierarchy of stacks. \n\nLinear message processing is a good and clear solution for many use cases. However, in some use cases there are hundreds, thousands or millions of middlewares and every message is relevant only to a small portion of those. This module attempts to address this problem.\n\nThis construct was designed with http framework in mind but the implemetation tries to be as neutral as possible, so it will be usable for other problem domains.\n\n**(WIP)**\n\n```\n+-----------------+\n| path: ['a']     |      A message to ['a', 'b', 'c'] will processed\n|                 |      by: f1, f2, f3, f4, f7, f8\n| stack: [f1, f2] |\n|                 |      While a message to ['a','c'] will be processed\n+------+----------+      by: f1, f2, f5, f6\n       |\n       |\n       |     +-------------------+\n       |     | path: ['a', 'b']  |\n       |     |                   |\n       +-----\u003e stack: [f3, f4]   |\n       |     |                   |\n       |     +---------+---------+      +---------------------+\n       |               |                | path: ['a','b','c'] |\n       |               +----------------\u003e                     |\n       |     +-------------------+      | stack: [f7, f8]     |\n       |     | path: ['a', 'c']  |      |                     |\n       |     |                   |      +---------------------+\n       +-----\u003e stack: [f5, f6]   |\n             |                   |\n             +-------------------+\n```\n\n## install\n\nWith [npm](https://npmjs.org) do:\n\n```\nnpm install --save hstacks\n```\n\n## example\n\nA rudimentary http server with middlewares\n\n```js\nvar HStacks = require('hstacks')\nvar http = require('http')\n\nvar hstacks = new HStacks()\n\n// mount some middlewares\n// this is the root\nhstacks.mount([''], function (req, res, next) {\n    console.log(req.url)\n    next()\n})\n\nhstacks.mount(['', 'a'], function (req, res, next) {\n    console.log('/a middleware')\n    res.end()\n})\n\nhstacks.mount(['', 'b'], function (req, res, next) {\n    console.log('/b middleware')\n    res.end()\n})\n\nhttp.createServer(function(req, res) {\n    hstacks.dispatch(req.url.split('/'), [req, res])\n})\n\n```\n\n## concepts\n### path\nA path inside a tree: e.g ```a-\u003eb-\u003ec```. A path is always represented by an array ```['a', 'b', 'c']```. Each path might hold a stack or middlewares and a special error middleware.\n\n### stack\nA stack is an array of middlewares nested inside a path in the tree. When middlewares are processed in a stack they are processed from index 0 to stack.length -1\n\n### middleware\nA middleware function is a part of a stack and takes the form of:\n```javascript\nfunction middleware(arg1, arg2, ... , next) {\n\n}\n```\n\nCalling ```next()```indicates that descendant stacks in the tree should also process the arguments.\nCalling ```next(err)``` will break the normal flow of execution and kick in the error middlewares\n\nA middleware is mounted on a path:\n```javascript\nhstacks.mount(['a', 'b'], function (msg, next) {\n    console.log(msg)\n    next()\n})\n\nhstacks.mount(['a', 'b'], function (msg, next) {\n    console.log('hey its that message...', msg)\n})\n```\n\nIn this example a-\u003eb-\u003ec has two middlewares handling messages\n\n### error middleware\nA special middleware the exists outside of any stack. An error middleware is invoked when a normal middleware calls its ```next()``` function with an error.\n\nMounting an error middleware is done through a different api:\n```javascript\nhstacks.mountErrorMiddleware(['a'], function (err, next) {\n\n})\n```\nAnd always have the same signature (as opposed to a normal middleware)\n\n## message processing flow\nWhen dispatching a message to the tree, the message is processes by each stack along the path from the root downwards. For example a message dispatched to path ```['a', 'b', 'c']``` will be processed by the stack that resides in ```['a']```, the stack in ```['a', 'b']``` and finally by ```['a', 'b', 'c']```. Each middleware in each stack most call its ```next()``` callback or execution is halted.\n\n## error processing flow\nWhen a middleware in one of the stacks calls its ```next()``` callback with an error, hstacks will look for an error middleware in the current path level and invoke it. If no error middleware is found, hstack will begin to traverse up the tree along the path looking to error middlewares. If none is found the error will be thrown (as a general rule one should always mount at least one error middleware)\n\n## api\n\n  - [new HStacks()](#new-hstackstrietrie-optional-contextobject-optional)\n  - [HStacks.dispatch()](#hstacksdispatchpatharrayargsarray)\n  - [HStacks.mount()](#hstacksmountpatharraymiddlewarefunction_iserrormiddlewareboolean)\n  - [HStacks.getStack()](#hstacksgetstackpatharray)\n  - [HStacks.getErrorMiddleware()](#hstacksgeterrormiddlewarepatharray)\n  - [HStacks.mountErrorMiddleware()](#hstacksmounterrormiddlewarepatharraymiddlewarefunction)\n\n#### new HStacks(trie:Trie (optional), context:Object (optional))\n\ncreate a new instance of hstack\n\n#### HStacks.dispatch(path:Array, args:Array)\n\ndispatch a message to hstacks, this message will be handled by all the middlewares that reside along the provided path.\n\n#### HStacks.mount(path:Array, middleware:Function)\n\nmount a middleware in the tree\n\n#### HStacks.getStack(path:Array)\n\ngets the stack a particular path\n\n#### HStacks.getErrorMiddleware(path:Array)\n\ngets the stack a particular path\n\n#### HStacks.mountErrorMiddleware(path:Array, middleware:Function)\n\nsee mount()\n\n## license\n\n[MIT](http://opensource.org/licenses/MIT) © [yaniv kessler](blog.yanivkessler.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkessler%2Fnode-hstacks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkessler%2Fnode-hstacks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkessler%2Fnode-hstacks/lists"}