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.
npm install @unicep/angularpnpm add @unicep/angularyarn add @unicep/angularbun add @unicep/angular@unicep/core is installed with it.
Usage with signals
Section titled “Usage with signals”injectCep must be called in an injection context, such as in a field or constructor of a component or service.
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.
injectCep(cep, options?)
Section titled “injectCep(cep, options?)”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)
Section titled “lookupCep(unicep, cep)”The Observable version, for RxJS pipelines. Unsubscribing cancels the request.
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)
Section titled “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:
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, such as CepNotFoundError or
AllProvidersFailedError. Every option is covered in Providers and
Core.