feat: add schedule helper (#226)

* feat: add schedule helper

* feat: dont alter handler behaviour

Co-authored-by: Netlify Team Account 1 <[email protected]>

Author: netlify-team-account-1

README.md

@@ -49,6 +49,30 @@ To use On-demand Builders, wrap your function handler with the `builder` functio
   export { handler }
   ```
 
+### Scheduled Functions (currently in beta)
+
+To use Scheduled Functions, wrap your function handler with the `schedule` function.
+
+- With JavaScript:
+
+  ```js
+  const { schedule } = require('@netlify/functions')
+
+  exports.handler = schedule('5 4 * * *', async () => {
+    console.log("It's 04:05 AM!")
+  })
+  ```
+
+- With TypeScript:
+
+  ```ts
+  import { schedule } from '@netlify/functions'
+
+  export const handler = schedule("5 4 * * *", async () => {
+    console.log("It's 04:05 AM!")
+  })
+  ```
+
 ### TypeScript typings
 
 This module exports typings for authoring Netlify Functions in TypeScript.

src/lib/schedule.ts

@@ -0,0 +1,21 @@
+import type { Handler } from '../function'
+
+/**
+ * Declares a function to run on a cron schedule.
+ * Not reachable via HTTP.
+ *
+ * @example
+ * ```
+ * export const handler = cron("5 4 * * *", async () => {
+ *   // ...
+ * })
+ * ```
+ *
+ * @param schedule expressed as cron string. see https://crontab.guru for help.
+ * @param handler
+ * @see https://docs.netlify.com/functions/<schedule>
+ * @tutorial https://announcement-blogpost
+ */
+const schedule = (cron: string, handler: Handler): Handler => handler
+
+export { schedule }

src/main.ts

@@ -1,2 +1,3 @@
 export { builder } from './lib/builder'
+export { schedule } from './lib/schedule'
 export * from './function'