# Angular

`@unicep/angular` gives you signal and RxJS bindings, for Angular 17 or newer and RxJS 7. The package uses no decorators, so it works with the standard Angular build.

```bash
npm install @unicep/angular
```

```bash
pnpm add @unicep/angular
```

```bash
yarn add @unicep/angular
```

```bash
bun add @unicep/angular
```

`@unicep/core` is installed with it.

## Usage with signals

`injectCep` must be called in an injection context, such as in a field or constructor of a component or service.

```ts
import { Component, signal } from '@angular/core';
import { injectCep } from '@unicep/angular';

@Component({
  selector: 'app-cep-field',
  template: `
    <input [value]="value()" (input)="value.set($any($event.target).value)" placeholder="00000-000" />
    @if (cep.isLoading()) { <p>Searching…</p> }
    @if (cep.error(); as error) { <p>{{ error.message }}</p> }
    @if (cep.data(); as address) {
      <p>{{ address.street }}, {{ address.neighborhood }} - {{ address.city }}/{{ address.state }}</p>
    }
  `,
})
export class CepFieldComponent {
  readonly value = signal('');
  readonly cep = injectCep(() => this.value());
}
```

The lookup only happens when the value is a valid CEP (with or without the hyphen). If the CEP changes, the previous result is dropped and the in-flight request is cancelled.

## API

### `injectCep(cep, options?)`

```ts
injectCep(cep: () => string | null | undefined, options?: {
  unicep?: Unicep;           // default: the instance provided through the UNICEP token
  enabled?: () => boolean;   // return false to pause lookups, default always enabled
}): {
  data: Signal<Address | undefined>;
  error: Signal<Error | undefined>;
  isLoading: Signal<boolean>; // true while a lookup for the current valid CEP is in flight
}
```

### `lookupCep(unicep, cep)`

The Observable version, for RxJS pipelines. Unsubscribing cancels the request.

```ts
import { inject } from '@angular/core';
import { lookupCep, UNICEP } from '@unicep/angular';

const unicep = inject(UNICEP);
lookupCep(unicep, '01310100').subscribe((address) => console.log(address));
```

### `UNICEP` and `provideUnicep(unicep)`

`UNICEP` is the injection token for the `Unicep` instance. By default it is a shared instance with all built-in providers. To change providers, timeout, cache or circuit breaker, provide your own:

```ts
import { ApplicationConfig } from '@angular/core';
import { Unicep, viaCep, brasilApi } from '@unicep/core';
import { provideUnicep } from '@unicep/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideUnicep(new Unicep({ providers: [viaCep(), brasilApi()], timeoutMs: 3000, cache: {} })),
  ],
};
```

`error` is one of the [unicep errors](/en/docs/errors), such as `CepNotFoundError` or
`AllProvidersFailedError`. Every option is covered in [Providers](/en/docs/providers) and
[Core](/en/docs/core).