diff --git a/README.md b/README.md index a7ff15b..d610215 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/package-lock.json b/package-lock.json index 7f0044b..311dccc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@azure/functions", - "version": "4.16.5", + "version": "4.17.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@azure/functions", - "version": "4.16.5", + "version": "4.17.1", "license": "MIT", "dependencies": { "@azure/functions-extensions-base": "0.3.0", diff --git a/package.json b/package.json index 7eec17b..ed71515 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@azure/functions", - "version": "4.17.0", + "version": "4.17.1", "description": "Microsoft Azure Functions NodeJS Framework", "keywords": [ "azure", diff --git a/src/constants.ts b/src/constants.ts index d67ffd5..9ce67ee 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -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'; diff --git a/src/index.ts b/src/index.ts index 75bde4d..96b399b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -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', diff --git a/src/trigger.ts b/src/trigger.ts index 1328c35..09a527c 100644 --- a/src/trigger.ts +++ b/src/trigger.ts @@ -198,6 +198,8 @@ export function connectorTrigger(options: ConnectorTriggerOptions): ConnectorTri } return addTriggerBindingName({ ...options, + deliveryMode: options.deliveryMode ?? 'Webhook', + cardinality: options.cardinality ?? 'one', type: 'connectorTrigger', }); } diff --git a/test/connectorTrigger.test.ts b/test/connectorTrigger.test.ts index b84bdb6..9f0805e 100644 --- a/test/connectorTrigger.test.ts +++ b/test/connectorTrigger.test.ts @@ -3,7 +3,8 @@ 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'; @@ -11,6 +12,14 @@ import { ConnectorTriggerFunctionOptions, ConnectorTriggerOptions, InvocationCon 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', @@ -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)}`, () => { @@ -143,6 +226,8 @@ describe('connectorTrigger', () => { [connectorTriggerBinding.name]: { type: 'connectorTrigger', name: connectorTriggerBinding.name, + deliveryMode: 'Webhook', + cardinality: 'one', direction: 'in', properties: { supportsDeferredBinding: 'false', @@ -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 = { deliveryMode: 'Poll', diff --git a/test/types/index.test.ts b/test/types/index.test.ts index 5240319..8f9f38b 100644 --- a/test/types/index.test.ts +++ b/test/types/index.test.ts @@ -79,6 +79,8 @@ function registerServiceBusTopic(): void { type ConnectorTriggerOptions = import('../../types').ConnectorTriggerOptions; type ConnectorTriggerFunctionOptions = import('../../types').ConnectorTriggerFunctionOptions; +declare const DeliveryMode: typeof import('../../types').DeliveryMode; +declare const Cardinality: typeof import('../../types').Cardinality; const connectorPollOptions: ConnectorTriggerFunctionOptions = { deliveryMode: 'Poll', @@ -98,6 +100,26 @@ const connectorPollOptions: ConnectorTriggerFunctionOptions = { 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('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 @@ -175,6 +197,7 @@ void registerServiceBusTopic; void connectorPollOptions; void connectorWebhookOptions; void connectorDefaultOptions; +void configureConnectorTriggerFromEnums; void configureConnectorTriggerFromVariables; void invalidConnectorOptions; void registerConnectorTrigger; diff --git a/test/types/isolatedModules.ts b/test/types/isolatedModules.ts index 1ec36b4..e253a09 100644 --- a/test/types/isolatedModules.ts +++ b/test/types/isolatedModules.ts @@ -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; diff --git a/types/connectorTrigger.d.ts b/types/connectorTrigger.d.ts index 92706a9..05a18aa 100644 --- a/types/connectorTrigger.d.ts +++ b/types/connectorTrigger.d.ts @@ -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 = (triggerInput: T, context: InvocationContext) => FunctionResult; export interface ConnectorTriggerFunctionOptions @@ -22,9 +38,10 @@ export interface ConnectorTriggerFunctionOptions export interface ConnectorTriggerOptions extends Record { /** - * 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`. @@ -38,10 +55,11 @@ export interface ConnectorTriggerOptions extends Record { 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`. */ - cardinality?: 'many' | 'one'; + cardinality?: Cardinality | 'many' | 'one'; /** * An optional per-function override for the maximum number of events per batch.