@kuketo/oidc-client-storage/README.md

This is an angular library which provides complete access to cookies in angular universal apps. Kuketo is esperanto for cookies.

# Angular Cookies Library Kuketo 🍪

This is an angular library which provides complete access to cookies in angular
universal apps. Kuketo is esperanto for cookies.

## Getting started

### Installation

```sh
npm install @kuketo/core @kuketo/browser [@kuketo/express] --save
# or
yarn add @kuketo/core @kuketo/browser [@kuketo/express]
```

### Usage

#### BrowserModule

The `KuketoBrowserModule` should be imported in your bootstrapped module (i.e.
`AppModule`) like this:

```ts
import { NgModule } from "@anular/core";
import { BrowserModule } from "@angular/platform-browser";
import { KuketoBrowserModule } from "@kuketo/browser";

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

@NgModule({
  imports: [BrowserModule, KuketoBrowserModule],
  declarations: [AppComponent],
  bootstrap: [AppComponent],
})
export class AppModule {}
```

It is possible to configure some defaults for writing cookies like this:

```ts
import { NgModule } from '@anular/core';
import { BrowserModule } from '@angular/platform-browser';
import { KuketoBrowserModule } from '@kuketo/browser';

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

@NgModule({
  imports: [
    BrowserModule,
    KuketoBrowserModule.withConfig({
      domain: '.example.com',
      path: '/'
      sameSite: 'strict',
      secure: true,
      maxAge: 10,
      expires: new Date(),
      skipUriEncoding: true,
    }),
  ],
  declarations: [ AppComponent ],
  bootstrap: [ AppComponent ],
})
export class AppModule {}
```

#### ServerModule

To use this library in angular universal you need to add the
`KuketoExpressModule` to your module definition for the server (i.e.
app.server.module.ts) like this:

```ts
import { NgModule } from "@angular/core";
import { ServerModule } from "@angular/platform-server";
import { KuketoExpressModule } from "@kuketo/express";

import { AppModule } from "./app.module";
import { AppComponent } from "./app.component";

@NgModule({
  imports: [AppModule, ServerModule, KuketoExpressModule],
  bootstrap: [AppComponent],
})
export class AppServerModule {}
```

and you must make sure both `req` and `res` are passed to `.render()` in your
server (i.e. `server.ts`) method like this:

```ts
server.get("*", (req, res) => {
  res.render(indexHtml, {
    req,
    res, // <-- this is missing in autogenerated server.ts
    providers: [{ provide: APP_BASE_HREF, useValue: req.baseUrl }],
  });
});
```

### CookiesService

To access cookies you can `Inject` the `CookiesService` into your `Component`,
`Directive`, `Service`, etc like this

```ts
import { Injectable } from "@angular/core";

import { CookiesService } from "@kuketo/core";

@Injectable()
export class SomeService {
  constructor(private cookies: CookiesService) {}

  readUserCookie(): string {
    return this.cookies.get("user");
  }
}
```

### Testing

The `@kuketo/core` package contains a testing module which enables tests to be
run in browser (i.e. karma) and node (i.e. jest) just the same.

```ts
describe("SomeService", () => {
  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [
        KuketoTestingModule.withConfig({
          maxCookieCount: 50,
          maxCookieSizeSum: 4093,
        }),
      ],
      providers: [{ provide: Location, useClass: SpyLocation }],
    });
    cookieStore = TestBed.inject(CookieStoreService);
  });

  it("can clear cookies", () => {
    expect(() => cookieStore.clear()).not.toThrow();
  });
});
```

### Comparison

| feature\package     | [ngx-cookie] | [ngx-cookie-service] | [@ngx-utils/cookies] | kuketo |
| ------------------- | ------------ | -------------------- | -------------------- | ------ |
| universal (express) | ✅           | 🚫                   | ✅                   | ✅     |
| testing support     | 🚫           | 🚫                   | 🚫                   | ✅     |
| schematic support   | 🚫           | 🚫                   | 🚫                   | WIP    |

[ngx-cookie]: https://www.npmjs.com/package/ngx-cookie-service
[@ngx-utils/cookies]: https://www.npmjs.com/package/@ngx-utils/cookies
[ngx-cookie-service]: https://www.npmjs.com/package/ngx-cookie-service