📖 Stackpress Library

Shared library used across Stackpress projects. Standardize type definitions across different projects and potentially save time for developers who would otherwise need to define these common types themselves.

Install

1$ npm i @stackpress/lib

Usage

• Data
  • Nest
  • ReadonlyMap
  • ReadonlyNest
  • ReadonlySet
• Event
  • EventEmitter
  • EventRouter
  • EventTerminal
• Queue
  • ItemQueue
  • TaskQueue
• File System
• Exception
• Reflection
• Status

Data

The data library helps with common data management scenarios.

• Nest
• ReadonlyMap
• ReadonlyNest
• ReadonlySet

Nest

A nest is a data object that contain other nested data objects or arrays.

1import { Nest, UnknownNest } from '@stackpress/lib';
2
3const nest = new Nest<UnknownNest>({
4  foo: { bar: 'zoo' }
5});
6
7registry.set('foo', 'zoo', ['foo', 'bar', 'zoo'])
8
9nest.has('foo') //--> true
10nest.has('foo', 'bar') //--> true
11nest.has('bar', 'foo') //--> false
12nest.get('foo', 'zoo') //--> ['foo', 'bar', 'zoo']
13nest.get('foo', 'zoo', 1) //--> 'bar'
14nest.get<string>('foo', 'zoo', 1) // as string
15
16registry.remove('foo', 'bar')
17
18nest.has('foo', 'bar') //--> false
19nest.has('foo', 'zoo') //--> true

Readonly Map

A type of Map that is readonly.

1import { ReadonlyMap } from  '@stackpress/lib';
2
3const map = new ReadonlyMap([['foo', 'bar'], ['bar', 'zoo']]);
4
5map.get('foo') //--> bar
6map.has('bar') //--> zoo
7
8map.entries() //--> [['foo', 'bar'], ['bar', 'zoo']]
9
10map.forEach(console.log);

Readonly Nest

A type of Nest that is readonly.

1import { ReadonlyNest, UnknownNest } from '@stackpress/lib';
2
3const nest = new Nest<UnknownNest>({
4  foo: { bar: 'zoo' }
5});
6
7nest.has('foo') //--> true
8nest.has('foo', 'bar') //--> true
9nest.has('bar', 'foo') //--> false
10nest.get('foo', 'zoo') //--> ['foo', 'bar', 'zoo']
11nest.get('foo', 'zoo', 1) //--> 'bar'
12nest.get<string>('foo', 'zoo', 1) // as string

Readonly Set

A type of Set that is readonly.

1import { ReadonlySet } from  '@stackpress/lib';
2
3const set = new ReadonlySet(['foo', 'bar', 'zoo']);
4
5set.size //--> 3
6set.has('bar') //--> true
7set.values() //--> ['foo', 'bar', 'zoo']
8
9set.forEach(console.log);

Event

The event library is a set of tools for event driven projects.

• EventEmitter
• EventRouter
• EventTerminal

EventEmitter

A class that implements the observer pattern for handling events. The interface follows node:events, but you can set priority levels per event action. EventEmitter works on server and browser.

1import { EventEmitter } from '@stackpress/lib';
2
3type EventMap = Record<string, [ number ]> & {
4  'trigger something': [ number ]
5};
6
7const emitter = new EventEmitter<EventMap>()
8
9emitter.on('trigger something', async x => {
10  console.log('something triggered', x + 1)
11})
12
13emitter.on(/trigger (something)/, async x => {
14  console.log('(something) triggered', x + 2)
15}, 2)
16
17await emitter.trigger('trigger something', 1)

EventRouter

An expressjs like router that uses EventEmitter in the back-end. Like EventEmitter, you can set priority levels per route and works also in the browser.

1import { EventRouter } from '@stackpress/lib';
2
3type RouteMap = Record<string, [ Map, Map ]>;
4
5const router = new EventRouter<RouteMap>()
6
7router.get('/foo/bar', async (req, res) => {
8  res.set('foo', 'bar')
9})
10
11router.all('/foo/bar', async (req, res) => {
12  res.set('bar', req.get('bar'))
13}, 2)
14
15//router.connect('/foo/bar', async (req, res) => {})
16//router.delete('/foo/bar', async (req, res) => {})
17//router.head('/foo/bar', async (req, res) => {})
18//router.options('/foo/bar', async (req, res) => {})
19//router.patch('/foo/bar', async (req, res) => {})
20//router.post('/foo/bar', async (req, res) => {})
21//router.put('/foo/bar', async (req, res) => {})
22//router.trace('/foo/bar', async (req, res) => {})
23//router.route('METHOD', '/foo/bar', async (req, res) => {})
24
25await router.emit('GET /foo/bar', new Map([['foo', 'zoo']]), new Map())

EventTerminal

A basic event driven cli toolset that uses events in the background. This enables using events on the command line.

1import { EventTerminal } from '@stackpress/lib';
2
3const cli = new EventTerminal(process.argv)
4
5cli.on('foo', async params => {
6  const foo = cli.expect([ 'foo', 'f' ], 'bar')
7  EventTerminal.info(foo) //--> bar
8  console.log(params) //--> { foo: 'bar' }
9})
10
11await cli.run()

Queue

The queue library is used to order items like callbacks and return the correct sequence.

• ItemQueue
• TaskQueue

ItemQueue

An item queue orders and consumes items sequencially (FIFO by default).

1import { ItemQueue } from '@stackpress/lib';
2
3const queue = new ItemQueue<string>()
4
5queue.push('a')
6
7queue.shift('b')
8
9queue.add('c', 10)
10
11queue.consume() //--> c
12queue.consume() //--> b
13queue.consume() //--> a

TaskQueue

A task queue orders and runs callbacks sequencially.

1import { TaskQueue } from '@stackpress/lib';
2
3const queue = new TaskQueue()
4
5queue.push(async x => {
6  console.log(x + 1)
7})
8
9queue.shift(async x => {
10  await Helper.sleep(2000)
11  console.log(x + 2)
12})
13
14queue.add(async x => {
15  console.log(x + 3)
16}, 10)
17
18await queue.run(1)

FileSystem

The file system library is an interface to interact with various file systems (ie. node:fs, virtual fs, browser fs, webpack fs, etc..) . It just requires the minimum functions compared to node:fs.

1interface FileSystem {
2  existsSync(path: string): boolean;
3  readFileSync(path: string, encoding: BufferEncoding): string;
4  realpathSync(string: string): string;
5  lstatSync(path: string): FileStat;
6  writeFileSync(path: string, data: string): void;
7  mkdirSync(path: string, options?: FileRecursiveOption): void
8  createReadStream(path: string): FileStream;
9  unlinkSync(path: string): void;
10};

A file loader is a set of common tools for locating, loading, importing files through out your project and node_modules.

1import { NodeFS, FileLoader } from '@stackpress/lib';
2
3const loader = new FileLoader(new NodeFS());
4
5loader.modules() //--> ./node_modules/
6loader.relative('/path/from/source.file', '/path/to/destination.file') //--> '../destination'
7loader.resolve('@/project/index') //--> [cwd]/project/index.js
8loader.absolute('../project/index') //--> [cwd]/project/index.js

Exception

Exceptions are used to give more information of an error that has occured.

1import { Exception } from '@stackpress/lib';
2
3const exception = new Exception('Invalid Parameters: %s', 2)
4  .withErrors({
5    name: 'required',
6    pass: 'missing number'
7  })
8  .withCode(500)
9  .withPosition(100, 200)
10
11exception.toResponse() //--> 
12/*{
13  code: 500,
14  status: 'Server Error',
15  error: 'Invalid Parameters 2',
16  start: 100,
17  end: 200
18}*/
19
20exception.trace() //--> [{ method, file, line, char}, ...]
21
22throw Exception.for('Unknown Error')

Reflection

Uses CallSite to produce proper stack tracing and information about functions being executed.

1import { Reflection } from '@stackpress/lib';
2
3const reflection = Reflection.stack(); //--> Reflection
4
5reflection[0].column //--> 3
6reflection[0].file //--> /path/to/file
7reflection[0].func //--> Function
8reflection[0].funcName //--> 'main'
9reflection[0].line //--> 3
10reflection[0].method //--> <none>
11reflection[0].self //--> undefined
12reflection[0].toObject()

Status Codes

Status codes inherit from http status codes and can be used to report statuses after major actions within your app has been executed.

1import { Status, getStatus } from '@stackpress/lib';
2
3getStatus(200) //--> { code: 200, status: 'OK' }
4
5Status.CONTINUE //--> { code: 100, status: 'Continue' }
6Status.PROCESSING //--> { code: 102, status: 'Processing' }
7Status.OK //--> { code: 200, status: 'OK' }
8Status.CREATED //--> { code: 201, status: 'Created' }
9Status.ACCEPTED //--> { code: 202, status: 'Accepted' }
10Status.EMPTY //--> { code: 204, status: 'No Content' }
11Status.RESET //--> { code: 205, status: 'Reset Content' }
12Status.PARTIAL //--> { code: 206, status: 'Partial Content' }
13Status.MOVED //--> { code: 301, status: 'Moved Permanently' }
14Status.FOUND //--> { code: 302, status: 'Found' }
15Status.REDIRECT //--> { code: 303, status: 'See Other' }
16Status.CACHE //--> { code: 304, status: 'Not Modified' }
17Status.TEMPORARY //--> { code: 307, status: 'Temporary Redirect' }
18Status.PERMANENT //--> { code: 308, status: 'Permanent Redirect' }
19Status.ABORT //--> { code: 309, status: 'Aborted' }
20Status.BAD_REQUEST //--> { code: 400, status: 'Bad Request' }
21Status.UNAUTHORIZED //--> { code: 401, status: 'Unauthorized' }
22Status.FORBIDDEN //--> { code: 403, status: 'Forbidden' }
23Status.NOT_FOUND //--> { code: 404, status: 'Not Found' }
24Status.BAD_METHOD //--> { code: 405, status: 'Method Not Allowed' }
25Status.NOT_ACCEPTABLE //--> { code: 406, status: 'Not Acceptable' }
26Status.REQUEST_TIMEOUT //--> { code: 408, status: 'Request Timeout' }
27Status.CONFLICT //--> { code: 409, status: 'Conflict' }
28Status.GONE //--> { code: 410, status: 'Gone' }
29Status.LENGTH_REQUIRED //--> { code: 411, status: 'Length Required' }
30Status.TOO_LARGE //--> { code: 413, status: 'Payload Too Large' }
31Status.TOO_LONG //--> { code: 414, status: 'URI Too Long' }
32Status.UNSUPPORTED_TYPE //--> { code: 415, status: 'Unsupported Media Type' }
33Status.BAD_RANGE //--> { code: 416, status: 'Range Not Satisfiable' }
34Status.BAD_EXPECTATION //--> { code: 417, status: 'Expectation Failed' }
35Status.MISDIRECTED //--> { code: 421, status: 'Misdirected Request' }
36Status.UNPROCESSABLE //--> { code: 422, status: 'Unprocessable Content' }
37Status.LOCKED //--> { code: 423, status: 'Locked' }
38Status.BAD_DEPENDENCY //--> { code: 424, status: 'Failed Dependency' }
39Status.UPGRADE_REQUIRED //--> { code: 426, status: 'Upgrade Required' }
40Status.BAD_PRECONDITION //--> { code: 428, status: 'Precondition Required' }
41Status.TOO_MANY //--> { code: 429, status: 'Too Many Requests' }
42Status.HEADER_TOO_LARGE //--> { code: 431, status: 'Request Header Fields Too Large' }
43Status.LEGAL_REASONS //--> { code: 451, status: 'Unavailable For Legal Reasons' }
44Status.ERROR //--> { code: 500, status: 'Internal Server Error' }
45Status.NOT_IMPLEMENTED //--> { code: 501, status: 'Not Implemented' }
46Status.BAD_GATEWAY //--> { code: 502, status: 'Bad Gateway' }
47Status.UNAVAILABLE //--> { code: 503, status: 'Service Unavailable' }
48Status.RESPONSE_TIMEOUT //--> { code: 504, status: 'Gateway Timeout' }
49Status.BAD_VERSION //--> { code: 505, status: 'HTTP Version Not Supported' }
50Status.INSUFFICIENT_STORAGE //--> { code: 507, status: 'Insufficient Storage' }
51Status.INFINITE_LOOP //--> { code: 508, status: 'Loop Detected' }
52Status.NETWORK_AUTHENTICATION_REQUIRED //--> { code: 511, status: 'Network Authentication Required' }