Efficient, tiny object pool
MIT License
Efficient, tiny object pool
import nage from 'nage';
// create your pool
const pool = nage();
// reserve an object from the pool
const object = pool.reserve();
// do your logic
// release object back to the pool
pool.release(object);
All typings for the internals are under the Nage
namespace. The available types:
type Entry = {
[key: string]: any;
[index: number]: any;
};
type Creator<Pooled> = () => Pooled;
type Handler<Pooled> = (entry: Pooled) => void;
type ResetHandler<Pooled> = (stack: Pooled[]) => void;
type Options<Pooled extends {} = Entry> = {
create?: Creator<Pooled>;
initialSize?: number;
name?: number | string | symbol;
onRelease?: Handler<Pooled>;
onReserve?: Handler<Pooled>;
onReset?: ResetHandler<Pooled>;
};
The pool itself is not namespaced, it should be available directly as NagePool
:
defaults to () => ({})
The method used to create a new object in the pool. The default returns an empty object, but if you have objects with a consistent structure it is more memory efficient to return an object with that structure to reduce the number of hidden classes created under-the-hood.
type Obj = {
name: string | null;
target: any;
}
const pool = nage<Obj>({
create() {
return {
name: null,
target: null,
};
},
});
NOTE: This function does not receive any arguments, and must return an object of some kind. This can be a standard POJO, array, Map, Set, etc., but it cannot be a primitive or null
.
defaults to 1
const pool = nage<Obj>({ initialSize: 10 });
The number of objects to prepopulate the pool with. If you expect a number of objects to be used in parallel, it is advised to prepopulate the pool with the number appropriate for the use-case.
defaults to Infinity
const pool = nage<Obj>({ maxSize: 10 });
The maximum number of objects that will live in the pool. If you have reserved an object from the pool and try to release it back to the pool, it will allow the object to be garbage collected.
NOTE: If you provide an initialSize
that is larger than the maxSize
, the maxSize
will be used as the initialSize
.
const pool = nage<Obj>({ name: 'custom-name' });
The name for the given pool. This doesn't impact anything at runtime, but can help with debugging as an identifier.
type Obj = { [key: string]: any };
const pool = nage<Obj>({
onReserve(object) {
object.reservedAt = Date.now();
},
});
Handler called for a newly-reserved item from the pool, called with the object prior to being returned. This method is handy if you want to prepopulate the object with some data.
type Obj = { [key: string]: any };
const pool = nage<Obj>({
onRelease(object) {
for (const key in object) {
object[key] = null;
}
},
});
Handler called for a newly-released item back into the pool, called with the object just prior to being added to the stack. This method is handy to perform cleanup of the object in preparation for future use.
const pool = nage<Obj>({
onReset(stack) {
stack.forEach((entry) => {
console.log(entry);
});
},
});
Handler called just prior to the stack being reset
. This method is handy if you need to take a snapshot of the existing pool prior to it being purged and repopulated.
Reserves an object from the pool. If no objects remain to be reserved, it will create a new one for you based on the create
method from options.
const object = pool.reserve();
Releases an object back to the pool from where it came from.
pool.release(object);
Reserves multiple objects from the pool. If no objects remain to be reserved, it will create new ones for you based on the create
method from options.
const object = pool.reserveN(10);
Releases multiple objects back to the pool from where it came from.
pool.releaseN([object, anotherObject]);
Resets the pool to its initial state, which is based on the initialSize
value from options.
pool.reset();
The number of objects in the pool available for reservation.
The number of objects in the pool unavailable because they are reserved.
The total number of objects in the pool, regardless of reservation status.
Standard stuff, clone the repo and npm install
dependencies. The npm scripts available:
benchmark
=> run the benchmark suite pitting moize
against other libraries in common use-casesbuild
=> run rollup to build the distributed files in dist
clean
=> run rimraf
on the dist
folderdev
=> run webpack dev server to run example app (playground!)dist
=> runs clean
and build
lint
=> runs ESLint against all files in the src
folderlint:fix
=> runs `lint``, fixing any errors if possibleprepublish
=> runs compile-for-publish
prepublish:compile
=> run lint
, test:coverage
, and dist
test
=> run test functions with NODE_ENV=test
test:coverage
=> run test
but with nyc
for coverage checkertest:watch
=> run test
, but with persistent watcher