Add docs on developing TypeScript functions

Fix section ID

Move TypeScript context object reference to the proper guide

Fix function header

Co-authored-by: Lance Ball <[email protected]>

Fix another function header

Co-authored-by: Lance Ball <[email protected]>

Improve wording

Co-authored-by: Lance Ball <[email protected]>

Fix yet another function header

Co-authored-by: Lance Ball <[email protected]>

Fix broken list

Add the step of installing dependencies

Substitute curl commands with kn func emit commands

Improve kn func emit examples

Several stylistic improvements

Make paragraph more precise

Co-authored-by: jrangelramos <[email protected]>

Add a comma

Use updated TypeScript code examples

Co-authored-by: Lance Ball <[email protected]>

Improvements to TypeScript code

Improve TypeScript code

Co-authored-by: jrangelramos <[email protected]>

Author: rh-max

_topic_map.yml

@@ -3122,6 +3122,8 @@ Topics:
     File: serverless-functions-getting-started
   - Name: Developing Node.js functions
     File: serverless-developing-nodejs-functions
+  - Name: Developing TypeScript functions
+    File: serverless-developing-typescript-functions
   - Name: Developing Golang functions
     File: serverless-developing-go-functions
   - Name: Developing Python functions

modules/serverless-testing-typescript-functions.adoc

@@ -0,0 +1,20 @@
+[id="serverless-testing-typescript-functions_{context}"]
+= Testing TypeScript functions
+
+TypeScript functions can be tested locally on your computer. In the default project that is created when you create a function using `kn func create`, there is a *test* folder that contains some simple unit and integration tests.
+
+.Procedure
+
+. If you have not previously run tests, install the dependencies first:
++
+[source,terminal]
+----
+$ npm install
+----
+
+. Run the tests:
++
+[source,terminal]
+----
+$ npm test
+----

modules/serverless-typescript-context-object-reference.adoc

@@ -0,0 +1,149 @@
+[id="serverless-typescript-context-object-reference_{context}"]
+= TypeScript context object reference
+
+The `context` object has several properties that can be accessed by the function developer.
+
+[id="serverless-typescript-context-object-reference-log_{context}"]
+== log
+
+Provides a logging object that can be used to write output to the cluster logs. The log adheres to the link:https://getpino.io/#/docs/api[Pino logging API].
+
+.Example log
+[source,javascript]
+----
+export function handle(context: Context): string {
+    // log the incoming request body's 'hello' parameter
+    if (context.body) {
+      context.log.info((context.body as Record<string, string>).hello);
+    } else {
+      context.log.info('No data received');
+    } 
+    return 'OK';
+} 
+
+----
+
+You can access the function by using the `kn func emit` command to invoke it:
+
+.Example command
+[source,terminal]
+----
+$ kn func emit --sink 'http://example.function.com'
+----
+
+.Example output
+[source,terminal]
+----
+{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"Processing customer"}
+----
+
+You can change the log level to one of `fatal`, `error`, `warn`, `info`, `debug`, `trace`, or `silent`. To do that, change the value of `logLevel` by assigning one of these values to the environment variable `FUNC_LOG_LEVEL` using the `config` command.
+
+[id="serverless-typescript-context-object-reference-query_{context}"]
+== query
+
+Returns the query string for the request, if any, as key-value pairs. These attributes are also found on the context object itself.
+
+.Example query
+[source,javascript]
+----
+export function handle(context: Context): string {
+      // log the 'name' query parameter
+    if (context.query) {
+      context.log.info((context.query as Record<string, string>).name);
+    } else {
+      context.log.info('No data received');
+    }
+    return 'OK';
+}
+
+----
+
+You can access the function by using the `kn func emit` command to invoke it:
+
+.Example command
+[source,terminal]
+----
+$ kn func emit --sink 'http://example.function.com' --data '{"name": "tiger"}'
+----
+
+.Example output
+[source,terminal]
+----
+{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"tiger"}
+{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"tiger"}
+----
+
+[id="serverless-typescript-context-object-reference-body_{context}"]
+== body
+
+Returns the request body, if any. If the request body contains JSON code, this will be parsed so that the attributes are directly available.
+
+.Example body
+[source,javascript]
+----
+export function handle(context: Context): string {
+    // log the incoming request body's 'hello' parameter
+    if (context.body) {
+      context.log.info((context.body as Record<string, string>).hello);
+    } else {
+      context.log.info('No data received');
+    } 
+    return 'OK';
+} 
+----
+
+You can access the function by using the `kn func emit` command to invoke it:
+
+.Example command
+[source,terminal]
+----
+$ kn func emit --sink 'http://example.function.com' --data '{"hello": "world"}'
+----
+
+.Example output
+[source,terminal]
+----
+{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"world"}
+----
+
+[id="serverless-typescript-context-object-reference-headers_{context}"]
+== headers
+
+Returns the HTTP request headers as an object.
+
+.Example header
+[source,javascript]
+----
+export function handle(context: Context): string {
+    // log the incoming request body's 'hello' parameter
+    if (context.body) {
+      context.log.info((context.headers as Record<string, string>)['custom-header']);
+    } else {
+      context.log.info('No data received');
+    } 
+    return 'OK';
+} 
+----
+
+You can access the function by using the `curl` command to invoke it:
+
+.Example command
+[source,terminal]
+----
+$ curl -H'x-custom-header: some-value’' http://example.function.com
+----
+
+.Example output
+[source,terminal]
+----
+{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"some-value"}
+----
+
+[id="serverless-typescript-context-object-reference-http-requests_{context}"]
+== HTTP requests
+
+method:: Returns the HTTP request method as a string.
+httpVersion:: Returns the HTTP version as a string.
+httpVersionMajor:: Returns the HTTP major version number as a string.
+httpVersionMinor:: Returns the HTTP minor version number as a string.

modules/serverless-typescript-function-return-values.adoc

@@ -0,0 +1,78 @@
+[id="serverless-typescript-function-return-values_{context}"]
+= TypeScript function return values
+
+Functions can return any valid JavaScript type or can have no return value. When a function has no return value specified, and no failure is indicated, the caller receives a `204 No Content` response.
+
+Functions can also return a CloudEvent or a `Message` object in order to push events into the Knative Eventing system. In this case, the developer is not required to understand or implement the CloudEvent messaging specification. Headers and other relevant information from the returned values are extracted and sent with the response.
+
+.Example
+[source,javascript]
+----
+export const handle: Invokable = function (
+  context: Context,
+  cloudevent?: CloudEvent
+): Message {
+  // process customer and return a new CloudEvent
+  const customer = cloudevent.data;
+  return HTTP.binary(
+    new CloudEvent({
+      source: 'customer.processor',
+      type: 'customer.processed'
+    })
+  );
+};
+----
+
+[id="serverless-typescript-function-return-values-headers_{context}"]
+== Returning headers
+
+You can set a response header by adding a `headers` property to the `return` object. These headers are extracted and sent with the response to the caller.
+
+.Example response header
+[source,javascript]
+----
+export function handle(context: Context, cloudevent?: CloudEvent): Record<string, any> {
+  // process customer and return custom headers
+  const customer = cloudevent.data as Record<string, any>;
+  return { headers: { 'customer-id': customer.id } };
+}
+----
+
+[id="serverless-typescript-function-return-values-status-codes_{context}"]
+== Returning status codes
+
+You can set a status code that is returned to the caller by adding a `statusCode` property to the `return` object:
+
+.Example status code
+[source,javascript]
+----
+export function handle(context: Context, cloudevent?: CloudEvent): Record<string, any> {
+  // process customer
+  const customer = cloudevent.data as Record<string, any>;
+  if (customer.restricted) {
+    return {
+      statusCode: 451
+    }
+  }
+  // business logic, then
+  return {
+    statusCode: 240
+  }
+}
+----
+
+Status codes can also be set for errors that are created and thrown by the function:
+
+.Example error status code
+[source,javascript]
+----
+export function handle(context: Context, cloudevent?: CloudEvent): Record<string, string> {
+  // process customer
+  const customer = cloudevent.data as Record<string, any>;
+  if (customer.restricted) {
+    const err = new Error(‘Unavailable for legal reasons’);
+    err.statusCode = 451;
+    throw err;
+  }
+}
+----

modules/serverless-typescript-functions-context-objects.adoc

@@ -0,0 +1,107 @@
+[id="serverless-typescript-functions-context-objects_{context}"]
+= TypeScript context objects
+
+Functions are invoked with a `context` object as the first parameter.
+
+.Example context object
+[source,javascript]
+----
+function handle(context:Context): string
+----
+
+This object provides access to the incoming HTTP request information, including the HTTP request method, any query strings or headers sent with the request, the HTTP version, and the request body. Incoming requests that contain a CloudEvent attach the incoming instance of the CloudEvent to the context object so that it can be accessed by using `context.cloudevent`.
+
+[id="serverless-typescript-functions-context-objects-methods_{context}"]
+== Context object methods
+
+The `context` object has a single method, `cloudEventResponse()`, that accepts a data value and returns a CloudEvent.
+
+In a Knative system, if a function deployed as a service is invoked by an event broker sending a CloudEvent, the broker examines the response. If the response is a CloudEvent, this event is handled by the broker.
+
+.Example context object method
+[source,javascript]
+----
+// Expects to receive a CloudEvent with customer data
+export function handle(context: Context, cloudevent?: CloudEvent): CloudEvent {
+  // process the customer
+  const customer = cloudevent.data;
+  const processed = processCustomer(customer);
+  return context.cloudEventResponse(customer)
+    .source('/customer/process')
+    .type('customer.processed')
+    .response();
+}
+----
+
+[id="serverless-typescript-functions-context-types_{context}"]
+== Context types
+
+The TypeScript type definition files export the following types for use in your functions.
+
+.Exported type definitions
+[source,javascript]
+----
+// Invokable is the expeted Function signature for user functions
+export interface Invokable {
+    (context: Context, cloudevent?: CloudEvent): any
+}
+
+// Logger can be used for structural logging to the console
+export interface Logger {
+  debug: (msg: any) => void,
+  info:  (msg: any) => void,
+  warn:  (msg: any) => void,
+  error: (msg: any) => void,
+  fatal: (msg: any) => void,
+  trace: (msg: any) => void,
+}
+
+// Context represents the function invocation context, and provides
+// access to the event itself as well as raw HTTP objects.
+export interface Context {
+    log: Logger;
+    req: IncomingMessage;
+    query?: Record<string, any>;
+    body?: Record<string, any>|string;
+    method: string;
+    headers: IncomingHttpHeaders;
+    httpVersion: string;
+    httpVersionMajor: number;
+    httpVersionMinor: number;
+    cloudevent: CloudEvent;
+    cloudEventResponse(data: string|object): CloudEventResponse;
+}
+
+// CloudEventResponse is a convenience class used to create
+// CloudEvents on function returns
+export interface CloudEventResponse {
+    id(id: string): CloudEventResponse;
+    source(source: string): CloudEventResponse;
+    type(type: string): CloudEventResponse;
+    version(version: string): CloudEventResponse;
+    response(): CloudEvent;
+}
+----
+
+[id="serverless-typescript-functions-context-objects-cloudevent-data_{context}"]
+== CloudEvent data
+
+If the incoming request is a CloudEvent, any data associated with the CloudEvent is extracted from the event and provided as a second parameter. For example, if a CloudEvent is received that contains a JSON string in its data property that is similar to the following:
+
+[source,json]
+----
+{
+  "customerId": "0123456",
+  "productId": "6543210"
+}
+----
+
+When invoked, the second parameter to the function, after the `context` object, will be a JavaScript object that has `customerId` and `productId` properties.
+
+.Example signature
+[source,javascript]
+----
+function handle(context: Context, cloudevent?: CloudEvent): CloudEvent
+----
+
+The `cloudevent` parameter in this example is a JavaScript object that contains the `customerId` and `productId` properties.