Skip to content

Commit

Permalink
feat!: remove ng modules (#210)
Browse files Browse the repository at this point in the history 
## PR Checklist

Please check if your PR fulfills the following requirements:

- [x] The commit message follows our guidelines: CONTRIBUTING.md#commit
- [x] Tests for the changes have been added (for bug fixes / features)
- [x] Docs have been added / updated (for bug fixes / features)

## PR Type

What kind of change does this PR introduce?

<!-- Please check the one that applies to this PR using "x". -->

```
[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Documentation content changes
[ ] Other... Please describe:
```

## What is the current behavior?

NgModules are deprecated but they are still part of the library

## What is the new behavior?

We have completely removed the NgModules from the source code.

## Does this PR introduce a breaking change?

```
[x] Yes
[ ] No
```

NgModules can not be used anymore to configure the library, only
provider functions can be used now.
  • Loading branch information
@NachoVazquez
NachoVazquez authored Jul 14, 2024
1 parent e6bd458 commit 7cb8941
Show file tree
Hide file tree
Showing 42 changed files with 70 additions and 1,211 deletions.
106 changes: 3 additions & 103 deletions packages/docs/lumberjack-docs-app/docs/log-drivers/http-driver.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,58 +115,14 @@ export interface LumberjackHttpDriverRetryOptions {

The `sendLog` method has been optimized to run outside Angular's `NgZone`, avoiding unnecessary change detection cycles.

### LumberjackHttpDriverModule
### provideLumberjackHttpDriver

> Note: Lumberjack NgModules are deprecated and will be removed in version 18. Use the Standalone API, provider functions, instead.
The `provideLumberjackHttpDriver` is similar to the `provideLumberjackConsoleDriver`.

The `LumberjackHttpDriverModule` is similar to the `LumberjackConsoleDriverModule`.

Novelty appears with the static `withOptions` function that allows us to pass `LumberjackHttpDriverOptions` to fall back to the settings in `LumberjackLogDriverConfig`.
Novelty appears with the `withHttpOptions` and `withHttpConfig` functions that allow to allow to configure the driver.

Additionally, we can configure the underlaying `HttpClient` by passing any features it receives like interceptors.

```typescript
@NgModule()
export class LumberjackHttpDriverModule {
/**
* Configure and register the HTTP driver, including settings that log drivers
* have in common.
*
* @param config Settings used by the HTTP driver.
*/
static forRoot(
config: LumberjackHttpDriverConfig,
...features: HttpClientFeatures
): ModuleWithProviders<LumberjackHttpDriverRootModule> {
return {
ngModule: LumberjackHttpDriverRootModule,
providers: [provideLumberjackHttpDriver(withHttpConfig(config), ...features)],
};
}

/**
* Configure and register the HTTP driver, but fall back on the default log
* driver settings for settings that log drivers have in common.
* @param options Settings used by the HTTP driver.
*/
static withOptions(
options: LumberjackHttpDriverOptions,
...features: HttpClientFeatures
): ModuleWithProviders<LumberjackHttpDriverRootModule> {
return {
ngModule: LumberjackHttpDriverRootModule,
providers: [provideLumberjackHttpDriver(withHttpOptions(options), ...features)],
};
}

constructor() {
throw new Error('Do not import LumberjackHttpDriverModule directly. Use LumberjackHttpDriverModule.forRoot.');
}
}
```

The most interesting behavior exist on the `provideLumberjackHttpDriver` function

```typescript
export type LumberjackHttpDriverConfigurationKind = 'options' | 'config';
export type LumberjackHttpDriverConfiguration<Kind extends LumberjackHttpDriverConfigurationKind> = {
Expand Down Expand Up @@ -226,65 +182,9 @@ export function provideLumberjackHttpDriver<Kind extends LumberjackHttpDriverCon
}
```

This is our Standalone API, ready for everyone using Angular >v14.

This is where the heaviest configuration happens and it is used to boost the classic APIs

The following is an example of how both API can be used

Classic:

> Note: Lumberjack NgModules are deprecated and will be removed in version 18. Use the Standalone API, provider functions, instead.
```typescript
@NgModule({
...,
imports: [
...,
LumberjackModule.forRoot(),
LumberjackConsoleDriverModule.forRoot(),
LumberjackHttpDriverModule.forRoot({
levels: ['error'],
origin: 'ForestApp',
retryOptions: { maxRetries: 5, delayMs: 250 },
storeUrl: '/api/logs',
},
withInterceptors([
(req, next) => {
const easy = inject(easyToken);
console.log('are interceptors working?', easy);
return next(req);
},
])
),
...
],
...
})
export class AppModule {}
```

or

```typescript
@NgModule({
...,
providers: [
...,
provideLumberjack(), provideLumberjackConsoleDriver(), provideLumberjackHttpDriver(withHttpConfig({
levels: ['error'],
origin: 'ForestApp',
retryOptions: { maxRetries: 5, delayMs: 250 },
storeUrl: '/api/logs',
}))
...
],
...
})
export class AppModule {}

Standalone:

bootstrapApplication(AppComponent, {
providers: [
provideLumberjack(),
Expand Down
83 changes: 4 additions & 79 deletions packages/docs/lumberjack-docs-app/docs/log-drivers/log-drivers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,35 +48,6 @@ Log drivers should make it possible to configure the logging levels on a per dri
For example, we could use the default logging levels for the console driver, but only enable the critical and error
levels for the HTTP driver as seen in the following example.

> Note: Lumberjack NgModules are deprecated and will be removed in version 18. Use the Standalone API, provider functions, instead.
```ts
import { NgModule } from '@angular/core';
import { Level as LumberjackLevel, LumberjackModule } from '@ngworker/lumberjack';
import { LumberjackConsoleDriverModule } from '@ngworker/lumberjack/console-driver';
import { LumberjackHttpDriverModule } from '@ngworker/lumberjack/http-driver';

@NgModule({
imports: [
LumberjackModule.forRoot({
levels: ['verbose'],
}),
LumberjackConsoleDriverModule.forRoot(),
LumberjackHttpDriverModule.forRoot({
levels: ['critical', 'error'],
origin: 'ForestApp',
storeUrl: '/api/logs',
retryOptions: { maxRetries: 5, delayMs: 250 },
}),
// (...)
],
// (...)
})
export class AppModule {}
```

Or use the standalone version of the API

```ts
import { bootstrapApplication } from '@angular/platform-browser';

Expand Down Expand Up @@ -229,7 +200,7 @@ export class ConsoleDriver implements LumberjackLogDriver<AnalyticsPayload> {
}
```

#### Creating a custom log driver module and provider functions
#### Creating a custom log driver provider functions

The provide functions provides configuration and other dependencies to a log driver. It also provides the log driver,
making
Expand Down Expand Up @@ -269,36 +240,6 @@ export function provideLumberjackConsoleDriver(config: Partial<LumberjackConsole
}
```

The driver module then acts as a wrapper for the log driver and the provide function.

> Note: Lumberjack NgModules are deprecated and will be removed in version 18. Use the Standalone API, provider functions, instead.
```ts
import { ModuleWithProviders, NgModule } from '@angular/core';

import { LumberjackConsoleDriverRootModule } from './lumberjack-console-driver-root.module';
import { LumberjackConsoleDriverConfig } from './lumberjack-console-driver.config';
import { provideLumberjackConsoleDriver } from './lumberjack-console-driver.providers';

@NgModule()
export class LumberjackConsoleDriverModule {
static forRoot(
config: Partial<LumberjackConsoleDriverConfig> = {}
): ModuleWithProviders<LumberjackConsoleDriverRootModule> {
return {
ngModule: LumberjackConsoleDriverRootModule,
providers: [provideLumberjackConsoleDriver(config)],
};
}

constructor() {
throw new Error('Do not import LumberjackConsoleDriverModule directly. Use LumberjackConsoleDriverModule.forRoot.');
}
}
```

The static `forRoot()` method provides the `consoleDriverConfigToken`.

If no configuration is passed, then the root `LogDriverConfig` is used.

```ts
Expand All @@ -314,33 +255,17 @@ This is possible because the `ConsoleDriver` has the same configuration options
only have to include the driver identifier since it cannot be predefined.

For adding custom settings,
see [LumberjackHttpDriver](https://github.com/ngworker/lumberjack/blob/main/packages/ngworker/lumberjack/http-driver/src/lib/configuration/lumberjack-http-driver-root.module.ts).
see [LumberjackHttpDriver](https://github.com/ngworker/lumberjack/blob/main/packages/ngworker/lumberjack/http-driver/src/lib/configuration/provide-lumberjack-http-driver.ts).

The most important thing about the `LumberjackConsoleDriverModule` is that it provides the `LumberjackConsoleDriver`
The most important thing about the `provideLumberjackConsoleDriver` function is that it provides the `LumberjackConsoleDriver`
using the `lumberjackLogDriverToken` with the `multi` flag on. This allows us to provide multiple log drivers for
Lumberjack at the same time.

#### Using a custom log driver

The last step is to import this module at the root module of our application, as seen in the first [_Usage_](../usage)
The last step is to provide this driver at the `bootstrapApplication` function, as seen in the first [_Usage_](../usage)
section.

> Note: Lumberjack NgModules are deprecated and will be removed in version 18. Use the Standalone API, provider functions, instead.
```ts
@NgModule({
imports: [
LumberjackModule.forRoot(),
ConsoleDriverModule.forRoot(),
// (...)
],
// (...)
})
export class AppModule {}
```

Or using the standalone API.

```typescript
import { bootstrapApplication } from '@angular/platform-browser';

Expand Down
53 changes: 4 additions & 49 deletions packages/docs/lumberjack-docs-app/docs/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,7 @@ title: Usage
> For a complete walkthrough video please
> visit [@ngworker/lumberjack v2 - Show & Tell BLS024](https://youtu.be/OV1ONtLAJnI)
To register Lumberjack, add `LumberjackModule.forRoot()` to your root or core Angular module.

> Note: Lumberjack NgModules are deprecated and will be removed in version 18. Use the Standalone API, provider functions, instead.
```ts
// (...)
import {LumberjackModule} from '@ngworker/lumberjack';

@NgModule({
imports: [
// (...)
LumberjackModule.forRoot(),
// (...)
],
// (...)
})
```

Or if you prefer a prefer standalone approach using the `provideLumberjack()`.
To register Lumberjack, add `provideLumberjack()` to your root or `bootstrapApplication` function.

```ts
bootstrapApplication(AppComponent, {
Expand All @@ -36,37 +18,10 @@ bootstrapApplication(AppComponent, {
});
```

You must also register the log driver modules for the log drivers that you want to enable.
You must also register the log driver provider functions for the log drivers that you want to enable.

If you want to add the `LumberjackHttpDriver` and the `LumberjackConsoleDriver`, add the following code

> Note: Lumberjack NgModules are deprecated and will be removed in version 18. Use the Standalone API, provider functions, instead.
```ts
// (...)
import { LumberjackModule } from '@ngworker/lumberjack';
import { LumberjackHttpDriverModule } from '@ngworker/lumberjack/http-driver';
import { LumberjackConsoleDriverModule } from '@ngworker/lumberjack/console-driver';

@NgModule({
imports: [
// (...)
LumberjackModule.forRoot(),
LumberjackConsoleDriverModule.forRoot(),
LumberjackHttpDriverModule.withOptions({
origin: '<app-name>',
storeUrl: '/api/logs',
retryOptions: { maxRetries: 5, delayMs: 250 },
}),
// (...)
],
// (...)
})
export class AppModule {}
```

Or using the standalone version

```ts
bootstrapApplication(AppComponent, {
providers: [
Expand Down Expand Up @@ -160,9 +115,9 @@ export class MyComponent implements OnInit {

> Each log level has its associated shorthand version: `'info'` is `logInfo`, `'debug'` is `logDebug`, etc.
### LumberjackModule and provideLumberjack
### provideLumberjack

Optionally, we can pass one or more options to `LumberjackModule.forRoot` or to the `provideLumberjack` function.
Optionally, we can pass one or more options to the `provideLumberjack` function.

| Option | Type | Optional? | Description |
| -------- | ------------------------------ | --------- | -------------------------------------------------------------------- |
Expand Down
4 changes: 2 additions & 2 deletions packages/examples/lumberjack-app/src/app/app.component.spec.ts
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
import { TestBed } from '@angular/core/testing';

import { LumberjackModule } from '@ngworker/lumberjack';
import { provideLumberjack } from '@ngworker/lumberjack';

import { AppComponent } from './app.component';

describe('AppComponent', () => {
beforeEach(async () => {
await TestBed.configureTestingModule({
imports: [LumberjackModule.forRoot()],
providers: [provideLumberjack()],
}).compileComponents();
});

Expand Down
4 changes: 0 additions & 4 deletions packages/internal/test-util/src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@
* Public API surface of @internal/test-util
*/

// Angular
export * from './lib/angular/expect-ng-module-to-be-guarded-against-direct-import';
export * from './lib/angular/expect-ng-module-to-be-guarded-against-duplicate-registration';

// Error-throwing driver
export * from './lib/error-throwing-driver/error-throwing-driver.config';
export * from './lib/error-throwing-driver/error-throwing.driver';
Expand Down
18 changes: 0 additions & 18 deletions ...nternal/test-util/src/lib/angular/expect-ng-module-to-be-guarded-against-direct-import.ts
View file

This file was deleted.

Loading

0 comments on commit 7cb8941

Please sign in to comment.