microcore

A 'framework' framework.

About

Why?
- I prefer smaller frameworks that allow for open ended extension with less dependencies to use for my own projects.
- Also, why not? 🤷
What?
- This project follows the 80/20 adage in supporting 20% of the features you use 80% of the time and will never be as featureful as dedicated projects for specific domains.
- Most modules provide an API with middleware for extension.
How?
- Currently, the best documentation is the source and tests in this package. As time permits, I will add more verbose documentation and examples.

Documentation

This is a collection of APIs mostly designed to be used together. The two main sources of documentation are this README.md and the Typedoc generated documentation.
This readme is meant to be an overview of this project while the documentation will be expanded at a later date.

Goals/Caveats:

The goal of this project is to be as small as possible.
API cronstructors provide a standard API and middleware extension framework. Specific use case functionality is supposed to use 'userland' middleware for implementation.
The targeted interpreters are node, browsers and Electron. Deno will be verified in the future.

Modules

Cache

The cache module provides the Cache<K, V> interface and two implementations: MapCache<K, V> class and createMapCache<K, V> constructor.
The MapCache class provides a simple implementation of the interface using a Map<K, V> to store values.
The createMapCache constructor implements middleware so that each method, except the name getter, can be extended via middleware. The last middleware in the chain is ./cache/middleware.ts and provides baseline cache method functionality.
For more detail, see source, middleware and tests.

MapCache Class Example:

// Not meant to be a complete example

import { MapCache } from '@caffedpkg/microcore';

type CustomType = {
  // typedef here
};

const mapCacheClassInstance = new MapCache<string, CustomType>();
const key = 'key';
const valueOne: CustomType = {};
mapCacheClassInstance.setValue(key, valueOne);
mapCacheClassInstance.hasValue(key) // true

createMapCache Constructor Example:

// Not meant to be a complete example

import { CACHE_ACTIONS, createMapCache } from '@caffedpkg/microcore';


type CustomType = {
  // typedef here
};

const myHashingFunction = (input) => {
  // logic here: MD5, SHA256 etc
};

const cacheKey = (hashingFunction: typeof Function) => {
  return (api: Record<any, any>) => {
    const { type } = api?.action;

    return (middleware: any) => {
      return (params: Record<any, any>) => {
        if (type === CACHE_ACTIONS.CACHE_SET_VALUE) {
          const hashKey = hashingFunction(value);
          return middleware({ key: `${key}-${hashkey}`, value });
        }
        return middleware(params);
      };
    };
  };
};

const mapCacheInstance = createMapCache<string, CustomType>({
  middleware: [{ middleware: cacheKey(myHashingFunction) }],
});

const key = 'key';
const valueOne: CustomType = {};
mapCacheInstance.setValue(key, valueOne);

Combinators

This is a collection of common functional combinators and are still heavily WIP.
Not yet recommended for use.
These will eventually allow for easy typing and code block integration.
For more detail, see source and tests.

Decorators

This is a convenience API based off of the TypeScript handbook documentation for decorators.
This implementation provides a Decorator<T, V, R>, type as well as a universal createDecorator<T, V, R> constructor with convenience constructors for each type of decorator.
This decorator API supports middleware for constructors so that functionality can be easily reused.
For more detailed examples, see decorator test specs.
For detailed parameter decorator implementations, see TypeScript's Handbook.
For more detail, see source and tests.

Class Decorator Example:

// Not meant to be a complete example

import { createClassDecorator } from '@caffedpkg/microcore';

const myDecoratorMiddleware = () => {} // see middleware docs

const middleware = [{
  middleware: myDecoratorMiddleware,
}];

const callback = (params: Record<any, any>) => {
  const {
    api,    // the middleware api
    target, // the class prototype
  } = params;

  // decorator code here
  // target is mutated and there is no return
};

const MyClassDecorator = createClassDecorator({
  callback,
  middleware,
});

@MyClassDecorator
class Test {
  constructor() {}
}

Class Method Decorator Example:

// Not meant to be a complete example

import { createClassMemberDecorator } from '@caffedpkg/microcore';

const myDecoratorMiddleware = () => {} // see middleware docs

const middleware = [{
  middleware: myDecoratorMiddleware,
}];

const callback = (params: Record<any, any>) => {
  const {
    api,          // the middleware api
    target,       // the class prototype
    propertyKey,  // the name of the method
    descriptor,   // The property descriptor of method definition
  } = params;


  // decorator code here
  // descriptor is mutated and there is no return
};

const MyClassMethodDecorator = createClassMemberDecorator({
  callback,
  middleware,
});

class Test {
  constructor() {}

  @MyClassMethodDecorator
  method() {}
}

Class Property Decorator Example:

// Not meant to be a complete example

import { createClassMemberDecorator } from '@caffedpkg/microcore';

const myDecoratorMiddleware = () => {} // see middleware docs

const middleware = [{
  middleware: myDecoratorMiddleware,
}];

const callback = (params: Record<any, any>) => {
  const {
    api,          // the middleware api
    target,       // the class prototype
    propertyKey,  // the name of the method
  } = params;

  // decorator code here
  // property accessors are mutated and there is no return
  // Easiest approach is using `Reflect.defineProperty(target, propertyKey, { get, set })`
};

const MyClassPropertyDecorator = createClassMemberDecorator({
  callback,
  middleware,
});


class Test {
  // Initialization with assignment is currently not supported with TypeScript property decorators
  @MyClassPropertyDecorator
  declare val : string;
}

Class Method Parameter Decorator Example:

// Not meant to be a complete example

import { createClassMemberDecorator } from '@caffedpkg/microcore';

const myDecoratorMiddleware = () => {} // see middleware docs

const middleware = [{
  middleware: myDecoratorMiddleware,
}];

const callback = (params: Record<any, any>) => {
  const {
    api,            // the middleware api
    parameterIndex, // parameter arity index
    propertyKey,    // the name of the method
  } = params;

  // decorator code here
  // no return
  // see https://www.typescriptlang.org/docs/handbook/decorators.html#parameter-decorators
};

const MyClassParameterDecorator = createClassMemberDecorator({
  callback,
  middleware,
});

class Test {
  method(@MyClassParameterDecorator param) {}
}

HTTTPClient

The HTTPClient<R> constructor uses types made from MDN and RFC documentation (see source for links) and simplifies creating fetch based requests with middleware support for request and response handling.
There are additional convenience constructors for creating APIs based on HTTPClient: clientFactory (scoped by HTTP method) and createHttpClient (all HTTP methods).
For more detail, see source and tests.

HTTPClient Request Handling Example:

// Not meant to be a complete example

import { HttpClient } from '@caffedpkg/microcore';

const myTokenGenerator = () => {};

const auth = (getToken: typeof Function) => {
  return (api: Record<any, any>) => {
    const { type } = api?.action;

    return (middleware: any) => {
      return (params: Record<any, any>) => {
        const {
          requestOptions,
        } = params;

        if (type === 'HTTP_REQUEST') {
          const token = getToken(requestOptions);
          const init = requestOptions[1] || {};
          if (init.headers) {
            init.headers.set('Authorization', `Bearer: ${token}`);
          } else {
            init.headers = new Headers([['Authorization', `Bearer: ${token}`]]);; 
          }
          requestOptions[1] = init;
        }

        return middleware(params);
      };
    };
  };
};

const client = HttpClient({
  middleware: [{ middleware: auth(myTokenGenerator) }],
  requestInitOptions: {
    method: 'GET',
  },
  request: 'https://url',
});

await client()
  .then(resp => {
    console.log(resp.headers.get('Authorization')); // `Bearer: ${token}`
  });

HTTPClient Response Handling Example:

// Not meant to be a complete example

import { HttpClient } from '@caffedpkg/microcore';

const myResponseParser = () => {};

const responseHandler = (api: Record<any, any>) => {
  const { type } = api?.action;

  return (middleware: any) => {
    return (params: Record<any, any>) => {
      const {
        result,
      } = params;

      if (type === 'HTTP_RESPONSE') {
        return myResponseParser(result);
      }
      return middleware(params);
    };
  };
};


const client = HttpClient({
  middleware: [{ middleware: responseHandler }],
  requestInitOptions: {
    method: 'GET',
  },
  request: 'https://url',
});

await client()
  .then(resp => {
    console.log(resp); // response was automatically handled by myResponseParser
  });

Logger

This API provides the createLogger<F> constructor with middleware support for line creation and line logging.
The default middleware provides JSON and string formatted support with console.log functionality. The makeJsonLine middleware automatically creates a SQLite compatible DATATIME timestamp for each logged line.

[${YEAR}-${DAY}-${MONTH}T${HOUR}:${MINUTE}:${SECOND}:${MS} | ${LEVEL} | ${PREFIX}]: ${DATA}

Middleware can be written to support custom telemetry workflows as well.
For more detail, see source, middleware and tests.

Logger Example:

// Not meant to be a complete example

import { createLogger } from '@caffedpkg/microcore';

const myFormatter = () => {}; // see ./logger/middlerware.ts 

const logger = createLogger<string>({
  formatter: myFormatter,
  prefix: 'Custom Prefix',
});

logger.log('test')
> [2049-04-4T12:00:00:000 | INFO | Custom Prefix]: test

Matcher

This API provides the createMatcher<A, B> constructor with middleware support for extendable assertions. The intended use case is for data validation eg: form fields, etc.
The createProxiedMatcher<A, B> allows for a flexible micro-assertion library extendable via middleware. This throws for any failure. These use cases might be less universally needed.
For more detail, see source and tests.

Matcher Example:

// Not meant to be a complete example

import { createMatcher } from '@caffedpkg/microcore';

const assertTrue = (_: any) => {
  return (_: any) => {
    return (...params: any[]) => {
      return params[0] === params[1];
    };
  }
};

type MyInputTypes = string | number;

const assertTrueMatcher = createMatcher<number | string>({
  middleware: [{ middleware: assertTrue }],
});

assertTrueMatcher('test', 'test') // true
assertTrueMatcher(false, 'false') // type error and also false

Proxied Matcher Example:

// Not meant to be a complete example

import { createProxiedMatcher } from '@caffedpkg/microcore';

const assertTrue = (_: any) => {
  return (_: any) => {
    return (...params: any[]) => {
      return params[0] === params[1];
    };
  }
};

const proxiedMatcher = createProxiedMatcher<number | string>({
  defaultTarget: {},
  methodName,
  middleware: [{ middleware: assertTrue }],
});

// matcher
proxiedMatcher.match(true, true);

// seperate expect() chain added, see source for features
proxiedMatcher.expect(true).to.eq(true);
proxiedMatcher.expect(true).to.be.true;

Middleware

This API provides a generic way to add middleware to any project. It is based on the apply/A+compose/B combinator approach that Redux uses.
This main entrypoint for this API is createMiddlewareApi<T, R> as it provides defaults for all parameters not passed in. If you want more control or a simpler implementation, use applyMiddleware<T, R> instead.
For more detail, see source and tests.
NOTE: The types/generics in this API might change in the future.

createMiddlewareApi Example:

// Not meant to be a complete example

import { createMiddlewareApi } from '@caffedpkg/microcore';

// API object constructor
const createApi = (...args) => {
  return {
    myOtherFunction() {},
    middleware() {}, // added to middleware chain
  };
};

// Array of middleware
const middleware =  [{
  data: {}, // to be used in transform for sorting, reshaping etc
  middleware: myMiddleWare,
}];

// compare function: (a, b) => -1, 0, 1
const sort = () => {};

// An Array.prorotype.reduce callback function
//  allows for arbitrary reshaping of the array of middleware.
const transform = (accumulator, current, index, array) => {};

// - Each one of these parameters has a corresponding
//   passthrough default if not provided
// - `middleware` is the only one really needed for most use cases
const api = createMiddlewareApi({
  createApi,
  middleware,
  sort,
  transform,
});

const result = api.middleware(args);

React utils

The one thing currently provided in mountRootComponent which handles bootstrapping the root React component into the document.body.
For more detail, see source and tests.

mountRootComponent Example:

// Not meant to be a complete example

import { mountRootComponent } from '@caffedpkg/microcore';
import { App } from './App';

const logger = () => {};
const renderFunc = () => {};

mountRootComponent({
  Component: App,
  logger, // optional. for error reporting. console.warn is default.
  renderFunc, // optional. handles mounting root component. defaults to React 18.x boilerplate. 
  rootElement: '#content-root', // CSS selector string or HTMLElement reference of root HTMLElement
});

Reducer

There are three APIs: createHistory, createReducer, and createStore. The history and reducer APIs are self contained while the store API combines them together.
The createHistoryController<T, S> API manages a History<T, S> instance with storing states in the past, current and future.
The createReducer<T, S> API manages a ReducerAction<T, S, A> collection. This can be reused in different stores for composable functionality.
The createStore<T, S, A> API combines a history controller and reducer collection to dispatch actions to. By default undo, redo and jumpToRevision are supported.
States have at least a revisionId and value property and actions have at least a type.
For more detail, see
- History: source and tests.
- Reducer: source and tests.
- Store: source, middleware and tests.

Store actions Example:

const reducers = {
  math: {
    add: numberAdd(state, action) => state,
  },
  strings: {
    add: stringAdd(state, action) => state,
  }
}

// results in actionOne = { type: 'math/add' }, and actionTwo = { type: 'strings/add' }

createHistoryController Example:

// Not meant to be a complete example

import { createHistoryController } from '@caffedpkg/microcore';

// can be pre-seeded with data
const history = {
  past: [],
  current: null,
  future: [],
};

const historyController = createHistoryController({ history });

createReducer Example:

// Not meant to be a complete example

import { createReducer } from '@caffedpkg/microcore';

const addAction = (state, action) => state;

const actions = {
  'ADD': addAction,
};

type MyStateValueType = {
  // fields
};

const reducer = createReducer<MyStateValueType>({
  actions,
});

createStore Example:

// Not meant to be a complete example

import { createStore } from '@caffedpkg/microcore';

const reducers = {
  math: {
    add: numberAdd, // (state, action) => state,
  },
  strings: {
    add: stringAdd, // (state, action) => state,
  }
}

const reducer = createStore({
  reducers,
});

const result = store.dispatch({
  type: 'math/add',
  data: {},
});

Resource

The resource API is for creating dynamically generated resource URLs for use with Workers and other frameworks that require URLs for construction.
There are two stand alone constructors createTextResource and createResource with the main difference in that createTextResource is restricted to all 'text/*' mime types and returns a tag function for string template setup and createResource returns a curried function for default plus instance param merging.
There is also a ResourceController which is a singleton controller designed to manage all resources per JavaScript realm.
For more detail, see source and tests.

createTextResource Example:

// Not meant to be a complete example

import { createTextResource } from '@caffedpkg/microcore';

const factory = x => x;
const name = 'test';

const textResource = createTextResource({
  factory, // optional. used for any custom resource content formatting.
  mimeType: 'text/javascript',
  name, // optional. the name of the resource.
})`
self.addEventListener('message', () => { console.log('i am being used for a Worker.'); });
`;

const worker = new Worker(textResource.url);

createResource Example:

// Not meant to be a complete example

import { createResource } from '@caffedpkg/microcore';

const factory = x => x;
const name = 'test';
const data = `self.addEventListener('message', () => { console.log('i am being used for a Worker.');`;

// Passing default parameters
const workerScript = createResource({
  factory, // optional. used for any custom resource content formatting.
  mimeType: 'text/javascript',
  name, // optional. the name of the resource.
});

const resource = workerScript({ data });
const worker = new Worker(resource.url);

ResourceController Example:

// Not meant to be a complete example

import { ResourceController } from '@caffedpkg/microcore';

const factory = x => x;
const name = 'test';
const data = `self.addEventListener('message', () => { console.log('I am being used for a Worker.');`;

const resourceController = new ResourceController();

const resource = resourceController.create({
  data,
  factory,
  mimeType: 'text/javascript',
  name,
});

const worker = new Worker(resource.url);
resourceController.delete(name);
const workerTwo = new Worker(resource.url); // will now fail

Transaction

This API is inspired by the combination of state reducer and database transaction patterns. Each stage in the transaction chain is handled by a middleware handler with data flowing throw them like a state reducer - state and action. Commit processes the steps in forward order while rollback() processes in reverse order to return related entities back into the origin state.
Each middleware should account for handling both TRANSACTION_COMMIT and TRANSACTION_ROLLBACK middleware actions.
For more detail, see source and tests.

Transaction Example:

// Not meant to be a complete example

import {
  type Action,
  type State,
  createTransaction,
} from '@caffedpkg/microcore';

const state: State<T> = {};
const action: Action<T> = {}; 
const middleware = []; // your transaction handling middleware

const createTxRunner = createTransaction({
  middleware,
});

const runner = createTxRunner(state, action);

try {
  runner.commit();
} catch(_: any) {
  runner.rollback();
}

URLManager

The URLManager class is a small extension of the existing URL interface to track generated object URLs from URL.createObjectUrl.
It also adds a convenience get/set for search params as Record<string, string>.
There is also a convenience static property currentUrl which returns a URLManager instance of globalThis.location.href.
For more detail, see source and tests.

URLManager Examples:

// Not meant to be a complete example

import { URLManager } from '@caffedpkg/microcore';

const blob = new Blob(['test'], { type 'text/plain' });

const url = URLManager.createObjectUrl(blob);
URLManager.objectUrls.includes(url); // true

// currentUrl
const currentUrl = URLManager.currentUrl;

// params
const url = new URLManager('https://domain?key=val');
console.log(url.params);
> {
>   key: 'val',
> }

url.params = { key: 'valTwo' };
console.log(url.href);
> 'https://dommain?key=valTwo'

Utils

This is a collection of functions mostly to support other APIs. These are tested but highly in flux. The rest will be documented in future versions when they are stabilized.
For more detail, see source and tests.

Utils Examples:

// Not meant to be a complete example

import { randomInteger, randomString } from '@caffedpkg/microcore';

const num = randomInteger(); // default 4 digits
typeof num === 'number';
const numTwo = randomInteger(20, { bigint: true });
typeof numTwo === 'bigint';
const str = randomString(); // default 10 characters
typeof str === 'string';
const strTwo = randomString(100);
typeof strTwo === 'string';
strTwo.length === 100; // true

Types

These are convenience types to support APIs here and in other projects.
For more detail, see source.

// Not meant to be a complete example

import type {
  AnyObject,
  ArrowFunction,
  Callable,
  Constructable,
  ConstructorFunction,
  MimeType,
} from '@caffedpkg/microcore';

// AnyObject<any> is essentially the same as Record<any, any>
const obj: AnyObject = {};

// ArrowFunction is a union type of all arrow function signatures
const myFunc = (callback: ArrowFunction): void => {};

// Callable is a conditional type used for defining arrow function signatures
// Constructable is a conditional type used for defining function constructor signatures
type MyType<R> = {
  callback: Callable<[first: FirstParamType, second: SecondParamType], any>;
  constructor: Constructable<any, R>;
}

// ConstructorFunction is a union type of all constructor function signatures
const myFunc = (constructor: ConstructorFunction): void => new constructor();

// MimeType is a string template type that constrains mime type strings to mostly valid
const mimeType: MimeType = 'image/png';
const badMimeType: MimeType = 'string/text';

Roadmap

NOTE: This project will follow semver guidelines

0.1.0
- First alpha release
0.2.0
- Bug fixes.
- The rest of the roadmap completed

Contributing

Currently, this package is for my project needs so large changes will be ignored.
Please see the contributing guidelines and the code of conduct for more information regarding submitting feature requests and bugs.

License

See LICENSE for more information.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
dist		dist
docs		docs
misc		misc
src		src
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitignore		.gitignore
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json

License

caffed/microcore

Folders and files

Latest commit

History

Repository files navigation

microcore

A 'framework' framework.

About

Documentation

Goals/Caveats:

Modules

Cache

MapCache Class Example:

createMapCache Constructor Example:

Combinators

Decorators

Class Decorator Example:

Class Method Decorator Example:

Class Property Decorator Example:

Class Method Parameter Decorator Example:

HTTTPClient

HTTPClient Request Handling Example:

HTTPClient Response Handling Example:

Logger

Logger Example:

Matcher

Matcher Example:

Proxied Matcher Example:

Middleware

createMiddlewareApi Example:

React utils

mountRootComponent Example:

Reducer

Store actions Example:

createHistoryController Example:

createReducer Example:

createStore Example:

Resource

createTextResource Example:

createResource Example:

ResourceController Example:

Transaction

Transaction Example:

URLManager

URLManager Examples:

Utils

Utils Examples:

Types

Roadmap

NOTE: This project will follow semver guidelines

Contributing

License

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages