Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat!: remove ng modules #210

Merged
merged 4 commits into from
Jul 14, 2024
Merged

feat!: remove ng modules #210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e9b4856
feat: remove depricated ngmodules
Jul 13, 2024
85ad2e4
feat: remove usage of any of the removed modules
Jul 14, 2024
df801bb
docs: update the docs to remove any mention to modules
Jul 14, 2024
8f98662
fix: failing tests
Jul 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 3 additions & 103 deletions packages/docs/lumberjack-docs-app/docs/log-drivers/http-driver.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop

This file was deleted.

Loading
Loading