{"id":6848,"date":"2023-01-16T13:15:12","date_gmt":"2023-01-16T12:15:12","guid":{"rendered":"https:\/\/www.angulararchitects.io\/?p=6848"},"modified":"2023-01-16T13:15:12","modified_gmt":"2023-01-16T12:15:12","slug":"patterns-for-custom-standalone-apis-in-angular","status":"publish","type":"post","link":"https:\/\/www.angulararchitects.io\/en\/blog\/patterns-for-custom-standalone-apis-in-angular\/","title":{"rendered":"Patterns for Custom Standalone APIs in Angular"},"content":{"rendered":"

Together with Standalone Components, the Angular team introduced Standalone APIs. They allow for setting up libraries in a more lightweight way. Examples of libraries currently providing Standalone APIs are the HttpClient<\/code> and the Router<\/code>. Also, NGRX is an early adopter of this idea.<\/p>\n

In this article, I present several patterns for writing custom Standalone APIs inferred from the before mentioned libraries. For each pattern, the following aspects are discussed: intentions behind the pattern, description, example implementation, examples for occurrences in the mentioned libraries, and variations for implementation details.<\/p>\n

Most of these patterns are especially interesting for library authors. They have the potential to improve the DX for the library's consumers. On the other side, most of them might be overkill for applications. <\/p>\n

\nBig thanks to Angular's Alex Rickabaugh<\/a> for proofreading and providing feedback!\n<\/p><\/blockquote>\n

\ud83d\udcc2 Source code used in examples<\/a><\/p>\n

Example<\/h2>\n

For presenting the inferred patterns, a simple logger library is used. This library is as simple as possible but as complex as needed to demonstrate the implementation of the patterns:<\/p>\n

<\/p>\n

Each log message has a LogLevel<\/code>, defined by an enum:<\/p>\n

export enum LogLevel {\n  DEBUG = 0,\n  INFO = 1,\n  ERROR = 2,\n}<\/code><\/pre>\n
For the sake of simplicity, we restrict our Logger library to just three log levels. <\/p>\n
An abstract LoggerConfig<\/code> defines the possible configuration options:<\/p>\n
export abstract class LoggerConfig {\n  abstract level: LogLevel;\n  abstract formatter: Type<LogFormatter>;\n  abstract appenders: Type<LogAppender>[];\n}<\/code><\/pre>\n
It's an abstract class on purpose, as interfaces cannot be used as tokens for DI. A constant of this class type defines the default values for the configuration options:<\/p>\n
export const defaultConfig: LoggerConfig = {\n  level: LogLevel.DEBUG,\n  formatter: DefaultLogFormatter,\n  appenders: [DefaultLogAppender],\n};<\/code><\/pre>\n
The LogFormatter<\/code> is used for formatting log messages before they are published via a LogAppender<\/code>:<\/p>\n
export abstract class LogFormatter {\n  abstract format(level: LogLevel, category: string, msg: string): string;\n}<\/code><\/pre>\n
Like the LoggerConfiguration<\/code>, the LogFormatter<\/code> is an abstract class used as a token. The consumer of the logger lib can adjust the formatting by providing its own implementation. As an alternative, they can go with a default implementation provided by the lib:<\/p>\n
@Injectable()\nexport class DefaultLogFormatter implements LogFormatter {\n  format(level: LogLevel, category: string, msg: string): string {\n    const levelString = LogLevel[level].padEnd(5);\n    return [${levelString}] ${category.toUpperCase()} ${msg}<\/code>;\n  }\n}<\/code><\/pre>\n
The LogAppender<\/code> is another exchangeable concept responsible for appending the log message to a log:<\/p>\n
export abstract class LogAppender {\n  abstract append(level: LogLevel, category: string, msg: string): void;\n}<\/code><\/pre>\n
The default implementation writes the message to the console:<\/p>\n
@Injectable()\nexport class DefaultLogAppender implements LogAppender {\n  append(level: LogLevel, category: string, msg: string): void {\n    console.log(category + ' ' + msg);\n  }\n}<\/code><\/pre>\n
While there can only be one LogFormatter<\/code>, the library supports several LogAppenders<\/code>. For instance, a first LogAppender<\/code> could write the message to the console while a second one could also send it to the server. <\/p>\n
To make this possible, the individual LogAppender<\/code>s are registered via multi providers. Hence, the Injector returns all of them within an array. As an array cannot be used as a DI token, the example uses an InjectionToken<\/code> instead:<\/p>\n
export const LOG_APPENDERS = new InjectionToken<LogAppender[]>("LOG_APPENDERS");<\/code><\/pre>\n
The LoggserService<\/code> itself receives the LoggerConfig<\/code>, the LogFormatter<\/code>, and an array with LogAppenders<\/code> via DI and allows to log messages for several LogLevels<\/code>:<\/p>\n
@Injectable()\nexport class LoggerService {\n  private config = inject(LoggerConfig);\n  private formatter = inject(LogFormatter);\n  private appenders = inject(LOG_APPENDERS);\n\n  log(level: LogLevel, category: string, msg: string): void {\n    if (level < this.config.level) {\n      return;\n    }\n    const formatted = this.formatter.format(level, category, msg);\n    for (const a of this.appenders) {\n      a.append(level, category, formatted);\n    }\n  }\n\n  error(category: string, msg: string): void {\n    this.log(LogLevel.ERROR, category, msg);\n  }\n\n  info(category: string, msg: string): void {\n    this.log(LogLevel.INFO, category, msg);\n  }\n\n  debug(category: string, msg: string): void {\n    this.log(LogLevel.DEBUG, category, msg);\n  }\n}<\/code><\/pre>\n
The Golden Rule<\/h2>\n
Before I start with presenting the inferred patterns, I want to stress out what I call the golden rule for providing services: <\/p>\n
\nWhenever possible, use @Injectable({providedIn: 'root'})<\/code>!\n<\/p><\/blockquote>\n
Especially in application code but in several situations in libraries, this is what you want to have: It's easy, tree-shakable, and even works with lazy loading. The latter aspect is less a merit of Angular than the underlying bundler: Everything that is just needed in a lazy bundle is put there. <\/p>\n
Pattern: Provider Factory<\/h2>\n
Intentions<\/h3>\n