@edd-kernel/contracts
v0.2.0-alpha.1
Published
Shared provider-agnostic EDD Kernel contracts.
Maintainers
Readme
@edd-kernel/contracts
Shared provider-agnostic contracts for EDD Kernel packages.
This package belongs to the core EDD Kernel layer. It owns the public client contract, shared option defaults, serialization helpers, queue normalization, consumer state helpers and common error-handling behavior used by every provider.
Repository: brunnofoggia/edd-kernel-js
Install
npm install @edd-kernel/contractsAn application usually installs @edd-kernel/factory and one provider instead. The
factory brings this package and re-exports it, so everything below is importable from
the factory as well:
npm install @edd-kernel/factory @edd-kernel/provider-aws-sqsUsage
Use the exported types to keep application code independent from a specific delivery provider:
import type {
EddDeliveryContext,
EddClient,
EventQueue,
EddEventTarget,
} from '@edd-kernel/contracts';
type EmailRequested = {
type: 'email.requested';
payload: {
to: string;
};
};
export async function publishEmailRequest(
client: EddClient,
target: EddEventTarget,
event: EmailRequested,
): Promise<void> {
await client.send(target, event);
}
export async function consumeEmailRequests(
client: EddClient,
queue: EventQueue,
handler: (event: EmailRequested, context: EddDeliveryContext) => Promise<void>,
): Promise<void> {
await client.consume(queue, handler);
}The consume API accepts one queue or a list of queues:
await client.consume([{ queueName: 'queue-a' }, { queueName: 'queue-b' }], handler, {
createIfNotExists: true,
maxMessagesPerQueue: 1,
});EddDeliveryContext.queue identifies the queue that produced the current message.
Main Exports
EddClientEddClientClassEddProviderFactoryEddSerializationModeEventEnvelopeEddEventTargetEventQueueEddDeliveryContextEddClientOptionsEddSendOptionsEddConsumeOptionsEddNormalizedClientOptionsEddNormalizedConsumeOptionsEddLoggerEddKernelErrorand the typed errors below it- the provider registry:
EddProviderName,EDD_PROVIDER_ALIASES,EDD_PROVIDER_TARGET_BY_NAME,normalizeProviderName,findProviderTarget
The full list is in
docs/edd-kernel-api-reference.md.
EddClientClass describes a concrete client constructor accepted by the
factory: shared options are the first argument and provider-specific options are
the second. providerName is an optional static identity on custom classes and
is declared by every built-in concrete provider class.
Defaults
serialization:EddSerializationMode.JsonautoIdempotencyKey:falsecreateIfNotExists:falseautoAck:falseunhandledErrorAction:nackconcurrency:1maxMessagesPerQueue:1
autoIdempotencyKey is only compatible with JSON serialization.
Per-send raw serialization uses EddSerializationMode.Raw as a send-side
override. Inbound deserialization is controlled by the client instance
serialization option.
JSON serialization rejects values such as top-level undefined, symbols and
functions when JSON.stringify cannot produce a string, and native failures such as
circular values or bigint. Both are reported as EddSerializationError.
Provider Guidance
This package is the contract. The shared behavior lives in
@edd-kernel/core, and a provider takes it from there:
option normalization, serialization, the client lifecycle, and EddPollingConsumer.
EddPollingConsumer owns the whole portable consume path — queue preparation, queue
rotation, concurrency, deserialization, autoAck, the unhandled-error action, the
warning for a message the handler never settled, active-delivery draining, idle waits
and polling error recovery. A provider supplies only transport through
EddPollingAdapter, so it is not free to implement a different contract.
Provider packages keep only provider-specific normalization and transport mapping.
