Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
34 changes: 34 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,40 @@ Use the exact values `'Poll'` or `'Webhook'` for `deliveryMode`, and `'one'` or
The connection and trigger configuration names must be strings; batch size, concurrency, and scaling threshold overrides must be numbers.
Poll delivery also now checks at registration that both `connection` and `triggerConfigName` are supplied.

### Connector trigger enums and defaults in 4.17.1

`DeliveryMode` and `Cardinality` are exported runtime enums for
both JavaScript and TypeScript:

```typescript
import { app, Cardinality, DeliveryMode } from '@azure/functions';

app.connectorTrigger('onNewEmail', {
deliveryMode: DeliveryMode.Poll,
cardinality: Cardinality.Many,
connection: 'ConnectorNamespace',
triggerConfigName: '%OnNewEmailTriggerConfigName%',
handler: async (events, context) => {
context.log('Received connector events.');
},
});
```

JavaScript can import the same values with
`const { app, DeliveryMode, Cardinality } = require('@azure/functions')`.
The existing supported string values remain valid: `'Poll'` / `'Webhook'` and
`'one'` / `'many'`. Unsupported or widened arbitrary strings remain type errors.
Enum members can also be used in unannotated configuration variables without
the string-widening problem described above.

Both `app.connectorTrigger` and `trigger.connectorTrigger` explicitly default
omitted `deliveryMode` to `'Webhook'` and omitted `cardinality` to `'one'` in the
generated binding metadata. Explicit settings are preserved, and caller options
are not modified. Batch size, concurrency, and scaling thresholds remain omitted
unless specified, so the host continues to supply their defaults.
These options also apply to typed connector helpers that use the base library's
`ConnectorTriggerOptions`.

## Usage

### TypeScript
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@azure/functions",
"version": "4.17.0",
"version": "4.17.1",
"description": "Microsoft Azure Functions NodeJS Framework",
"keywords": [
"azure",
Expand Down
2 changes: 1 addition & 1 deletion src/constants.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License.

export const version = '4.17.0';
export const version = '4.17.1';

export const returnBindingKey = '$return';
10 changes: 10 additions & 0 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,16 @@ export { Disposable } from './utils/Disposable';
export { McpContent } from './utils/mcpContentMarker';
export { arg } from './utils/toolProperties';

export enum DeliveryMode {
Webhook = 'Webhook',
Poll = 'Poll',
}

export enum Cardinality {
One = 'one',
Many = 'many',
}

export enum CosmosDBChangeFeedMode {
LatestVersion = 'LatestVersion',
AllVersionsAndDeletes = 'AllVersionsAndDeletes',
Expand Down
2 changes: 2 additions & 0 deletions src/trigger.ts
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,8 @@ export function connectorTrigger(options: ConnectorTriggerOptions): ConnectorTri
}
return addTriggerBindingName({
...options,
deliveryMode: options.deliveryMode ?? 'Webhook',
cardinality: options.cardinality ?? 'one',
type: 'connectorTrigger',
});
}
Expand Down
129 changes: 124 additions & 5 deletions test/connectorTrigger.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,23 @@

import 'mocha';
import { expect } from 'chai';
import { app, trigger } from '../src';
import * as sinon from 'sinon';
import { app, Cardinality, DeliveryMode, trigger } from '../src';
import { fromRpcTypedData } from '../src/converters/fromRpcTypedData';
import { toCoreFunctionMetadata } from '../src/converters/toCoreFunctionMetadata';
import { ConnectorTriggerFunctionOptions, ConnectorTriggerOptions, InvocationContext } from '../types';

describe('connectorTrigger', () => {
const _handler = (_triggerInput: unknown, _context: InvocationContext) => {};

it('should export the supported delivery modes as runtime enum values', () => {
expect(DeliveryMode).to.deep.equal({ Webhook: 'Webhook', Poll: 'Poll' });
});

it('should export the supported cardinalities as runtime enum values', () => {
expect(Cardinality).to.deep.equal({ One: 'one', Many: 'many' });
});

describe('trigger.connectorTrigger', () => {
const pollOptions: ConnectorTriggerOptions = {
deliveryMode: 'Poll',
Expand Down Expand Up @@ -55,20 +64,94 @@ describe('connectorTrigger', () => {
expect(trigger.connectorTrigger(options)).to.include(options);
});

it('should leave optional polling settings omitted so the host supplies defaults', () => {
it('should leave numeric polling settings omitted so the host supplies defaults', () => {
const result = trigger.connectorTrigger(pollOptions);

expect(result).to.have.all.keys('name', 'type', 'deliveryMode', 'connection', 'triggerConfigName');
expect(result).to.have.all.keys(
'name',
'type',
'deliveryMode',
'connection',
'triggerConfigName',
'cardinality'
);
expect(result.cardinality).to.equal('one');
});

it('should default to Webhook delivery and one event', () => {
const result = trigger.connectorTrigger({});

expect(result).to.have.all.keys('name', 'type', 'deliveryMode', 'cardinality');
expect(result).to.include({ deliveryMode: 'Webhook', cardinality: 'one' });
});

it('should apply defaults to explicitly undefined settings', () => {
expect(trigger.connectorTrigger({ deliveryMode: undefined, cardinality: undefined })).to.include({
deliveryMode: 'Webhook',
cardinality: 'one',
});
});

it('should not mutate caller options when applying defaults', () => {
const options: ConnectorTriggerOptions = Object.freeze({});

expect(trigger.connectorTrigger(options)).to.include({ deliveryMode: 'Webhook', cardinality: 'one' });
expect(options).to.deep.equal({});
});

it('should leave the default delivery mode omitted', () => {
expect(trigger.connectorTrigger({})).to.have.all.keys('name', 'type');
it('should generate the same binding name for omitted and explicit defaults', () => {
expect(trigger.connectorTrigger({}).name).to.equal(
trigger.connectorTrigger({
deliveryMode: DeliveryMode.Webhook,
cardinality: Cardinality.One,
}).name
);
});

it('should accept Webhook without polling settings', () => {
expect(trigger.connectorTrigger({ deliveryMode: 'Webhook' })).to.include({ deliveryMode: 'Webhook' });
});

for (const [label, deliveryMode] of [
['enum', DeliveryMode.Poll],
['string', 'Poll'],
] as const) {
for (const cardinality of [Cardinality.One, Cardinality.Many]) {
it(`should accept ${label} Poll delivery with cardinality ${cardinality}`, () => {
expect(trigger.connectorTrigger({ ...pollOptions, deliveryMode, cardinality })).to.include({
deliveryMode: 'Poll',
cardinality,
});
});
}

it(`should still require connection settings for ${label} Poll delivery`, () => {
expect(() => trigger.connectorTrigger({ deliveryMode })).to.throw(
'The following options are required for Poll delivery mode: connection, triggerConfigName'
);
});
}

it('should preserve explicitly selected Webhook enum and many cardinality', () => {
expect(
trigger.connectorTrigger({
deliveryMode: DeliveryMode.Webhook,
cardinality: Cardinality.Many,
})
).to.include({ deliveryMode: 'Webhook', cardinality: 'many' });
});

it('should default only omitted settings', () => {
expect(trigger.connectorTrigger({ cardinality: 'many' })).to.include({
deliveryMode: 'Webhook',
cardinality: 'many',
});
expect(trigger.connectorTrigger({ ...pollOptions, deliveryMode: DeliveryMode.Poll })).to.include({
deliveryMode: 'Poll',
cardinality: 'one',
});
});

for (const key of ['connection', 'triggerConfigName']) {
for (const value of [undefined, null]) {
it(`should require ${key} in Poll mode when it is ${String(value)}`, () => {
Expand Down Expand Up @@ -143,6 +226,8 @@ describe('connectorTrigger', () => {
[connectorTriggerBinding.name]: {
type: 'connectorTrigger',
name: connectorTriggerBinding.name,
deliveryMode: 'Webhook',
cardinality: 'one',
direction: 'in',
properties: {
supportsDeferredBinding: 'false',
Expand All @@ -155,6 +240,40 @@ describe('connectorTrigger', () => {
});

describe('app.connectorTrigger', () => {
afterEach(() => {
sinon.restore();
});

it('should apply default metadata during function registration', () => {
const createTrigger = sinon.spy(trigger, 'connectorTrigger');

app.connectorTrigger('defaultConnectorTrigger', { handler: _handler });

sinon.assert.calledOnce(createTrigger);
expect(createTrigger.firstCall.returnValue).to.include({
deliveryMode: 'Webhook',
cardinality: 'one',
});
});

it('should accept enum options during function registration', () => {
const createTrigger = sinon.spy(trigger, 'connectorTrigger');

app.connectorTrigger('enumConnectorTrigger', {
deliveryMode: DeliveryMode.Poll,
cardinality: Cardinality.Many,
connection: 'ConnectorNamespace',
triggerConfigName: 'config',
handler: _handler,
});

sinon.assert.calledOnce(createTrigger);
expect(createTrigger.firstCall.returnValue).to.include({
deliveryMode: 'Poll',
cardinality: 'many',
});
});

it('should register a typed batch handler with polling settings', () => {
const options: ConnectorTriggerFunctionOptions<string[]> = {
deliveryMode: 'Poll',
Expand Down
23 changes: 23 additions & 0 deletions test/types/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,8 @@ function registerServiceBusTopic(): void {

type ConnectorTriggerOptions = import('../../types').ConnectorTriggerOptions;
type ConnectorTriggerFunctionOptions<T = unknown> = import('../../types').ConnectorTriggerFunctionOptions<T>;
declare const DeliveryMode: typeof import('../../types').DeliveryMode;
declare const Cardinality: typeof import('../../types').Cardinality;

const connectorPollOptions: ConnectorTriggerFunctionOptions<TodoItem[]> = {
deliveryMode: 'Poll',
Expand All @@ -98,6 +100,26 @@ const connectorPollOptions: ConnectorTriggerFunctionOptions<TodoItem[]> = {
const connectorWebhookOptions: ConnectorTriggerOptions = { deliveryMode: 'Webhook' };
const connectorDefaultOptions: ConnectorTriggerOptions = {};

function configureConnectorTriggerFromEnums(): void {
const options = {
deliveryMode: DeliveryMode.Poll,
cardinality: Cardinality.Many,
connection: 'ConnectorNamespace',
triggerConfigName: '%TriggerConfigName%',
};
trigger.connectorTrigger(options);
app.connectorTrigger<TodoItem[]>('enumConnector', { ...options, handler: () => {} });

const webhookOptions: ConnectorTriggerOptions = {
deliveryMode: DeliveryMode.Webhook,
cardinality: Cardinality.One,
};
trigger.connectorTrigger(webhookOptions);

trigger.connectorTrigger({ deliveryMode: DeliveryMode.Poll, cardinality: 'many' });
trigger.connectorTrigger({ deliveryMode: 'Webhook', cardinality: Cardinality.One });
}

function configureConnectorTriggerFromVariables(): void {
const widenedOptions = { deliveryMode: 'Webhook' };
// @ts-expect-error unannotated configuration variables widen deliveryMode to string
Expand Down Expand Up @@ -175,6 +197,7 @@ void registerServiceBusTopic;
void connectorPollOptions;
void connectorWebhookOptions;
void connectorDefaultOptions;
void configureConnectorTriggerFromEnums;
void configureConnectorTriggerFromVariables;
void invalidConnectorOptions;
void registerConnectorTrigger;
Expand Down
10 changes: 9 additions & 1 deletion test/types/isolatedModules.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License.

import { CosmosDBv4ChangeFeedMode } from '../../types';
import { Cardinality, CosmosDBv4ChangeFeedMode, DeliveryMode } from '../../types';

const latestVersionMode = CosmosDBv4ChangeFeedMode.LatestVersion;
const allVersionsAndDeletesMode = CosmosDBv4ChangeFeedMode.AllVersionsAndDeletes;
const pollDeliveryMode = DeliveryMode.Poll;
const webhookDeliveryMode = DeliveryMode.Webhook;
const singleEventCardinality = Cardinality.One;
const batchCardinality = Cardinality.Many;

void latestVersionMode;
void allVersionsAndDeletesMode;
void pollDeliveryMode;
void webhookDeliveryMode;
void singleEventCardinality;
void batchCardinality;
26 changes: 22 additions & 4 deletions types/connectorTrigger.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,22 @@
import { FunctionOptions, FunctionResult, FunctionTrigger, RetryOptions } from './index';
import { InvocationContext } from './InvocationContext';

/**
* The connector event delivery mode.
*/
export enum DeliveryMode {
Webhook = 'Webhook',
Poll = 'Poll',
}

/**
* The number of connector events passed to each function invocation.
*/
export enum Cardinality {
One = 'one',
Many = 'many',
}

export type ConnectorTriggerHandler<T = unknown> = (triggerInput: T, context: InvocationContext) => FunctionResult;

export interface ConnectorTriggerFunctionOptions<T = unknown>
Expand All @@ -22,9 +38,10 @@ export interface ConnectorTriggerFunctionOptions<T = unknown>

export interface ConnectorTriggerOptions extends Record<string, unknown> {
/**
* The connector event delivery mode. If omitted, the Functions host defaults to `Webhook`.
* The connector event delivery mode. Accepts enum members or the supported string values.
* Defaults to `Webhook` when omitted.
*/
deliveryMode?: 'Poll' | 'Webhook';
deliveryMode?: DeliveryMode | 'Poll' | 'Webhook';

/**
* The connector connection setting. Required when `deliveryMode` is `Poll`.
Expand All @@ -38,10 +55,11 @@ export interface ConnectorTriggerOptions extends Record<string, unknown> {
triggerConfigName?: string;

/**
* Set to `many` to enable batching. If omitted or set to `one`, a single event is passed to the function.
* Set to `many` to enable batching. Accepts enum members or the supported string values.
* Defaults to `one`, which passes a single event to the function.
* For batches, use an array as the handler's payload type, for example `app.connectorTrigger<MyEvent[]>`.
*/
cardinality?: 'many' | 'one';
cardinality?: Cardinality | 'many' | 'one';

/**
* An optional per-function override for the maximum number of events per batch.
Expand Down
Loading