Null-Object

A tiny runtime type-safe polymorphic noop object that substitutes for your a real implementation without side effects.

See Null Object pattern ¹.

Package Status

Contents

• Basic Usage
• Summary
• Usage
  • The Convenience noop Function
• Maintenance
  • Contributions
• License

Basic Usage

Install the package.

npm install @wherejuly/null-object

Null-Object:

import{nullObject}from'@wherejuly/null-object';constlogger=config.log ? realLogger : nullObject<Logger>();logger.info('User signed in');// Always safe to call any method or access property on a null-object

A bundled noop function just for convenience:

import{noop}from'@wherejuly/null-object';noop();// returns `undefined`noop(1,'a',{b: 'c'});// as well silently acccepts any arguments

Summary

It is often useful to silently replace an optional dependency, service, or plugin that is not available in some environment (e.g. stub metrics service in development and stage environments).

It is also convenient to use in test to replace dependency objects you do not want to mock but still have to provide into the SUT. Especially, the objects that have the methods to be called by the SUT.

The package provides a safe fallback for any expected object interface by returning a no-op implementation object. It enables cleaner and more robust code due to no null checks or conditional logic.

Any methods called on it are noop, including chained ones. Methods silently accept arbitrary arguments. Access any properties, including nested, silently assign to properties.

Common use cases include:

• Optional services like logging, analytics, metrics:

  constmetrics=prod ? nullObject<Metrics>() : devMetrics;

• Provide a noop plugin when none is installed:

  constplugin=userProvidedPlugin??nullObject<Plugin>();

• Avoid conditional logic in consumers via default parameter:

  functioncreateHandler(callbacks: Callbacks=nullObject<Callbacks>()){callbacks.onReady();// Always callable}

• Middleware chains:

  constmiddleware=[authMiddleware,config.enableAudit ? auditMiddleware : nullObject<Middleware>()];

Usage

The signature:

functionnullObject<T=Record<string,any>>(name?: string): T;

Call any method, chained if needed, with arbitrary arguments, access any property, including nested and do nothing. Optionally provide null-object with the actual object type to ensure type safety.

typeTSomeActualHandler={method: any;prop: any};// May come as third-party typeconstsilent=nullObject<TSomeActualHandler>();// Could also use it untyped: `const silent = nullObject()`silent.method().another('arbitrary','args',123,true);silent.prop.method('arbitrary','args',123,true).more;

Help debugging with .toString() and optional named identity.

constlogger=config.log ? realLogger : nullObject<Logger>();constname=logger.toString();// name === [NullObject]// orconstlogger=config.log ? realLogger : nullObject<Logger>('Logger');constname=logger.toString();// name === [NullObject: Logger]

Can silently accept assignments to any property including nested.

constplugin=userProvidedPlugin??nullObject<Plugin>();plugin.settings.some=true;

The Convenience noop Function

The package also provides the noop function so that you do not have to import another package for it.

noop();// returns `undefined`noop(1,'a',true,null);// Accepts arbitrary arguments without throwingfunctiononEvent(callback: ()=>void=noop){callback();// Safe to call without checking}

Maintenance

The package is written in TypeScript with the informative JSDoc blocks available on hover for public interface (e.g. in VS Code) for comfortable programmatic usage. The code is carefully crafted with TDD allowing simple extension. The project is production-ready and actively maintained.

Contributions

Filling issues, questions in Discussions are all welcome.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Footnotes

1. Kerievsky J., Refactoring to Patterns (2004), p. 343; Fowler M., Refactoring (2018), p. 289 under "Introduce Special Case" title. ↩