Class-as-a-Function Pattern

by Josh Basch on August 13th, 2024

In many languages, function and method parameters may be assigned default values allowing the argument to be omitted in calls. Many languages also offer named parameters, which aid in API self-documentation. Pkl methods do not provide either feature, but one way to achieve similar results is the "class-as-a-function" (CaaF) pattern.

Usage

In the class-as-a-function pattern, a class is created that accepts "input" properties and has one or more fixed "output" properties.

Input properties are normal class properties. They are named, may have a type annotation, and may be defined with default values. Default values can be static values or may be derived from other properties.

Output properties derive their value from the input properties. They are typically marked as fixed so they may not be overridden when amending instances of the class.

Example

class GreetingFunction {
  /// The name that should be greeted.
  name: String (1)

  /// The phrase used to greet [name].
  greeting: String = "Hello" (2)

  /// The derived greeting.
  fixed message: String = "\(greeting), \(name)!" (3)
}

greetPigeon: String = new GreetingFunction { name = "Pigeon" }.message (4)

greetHawk: String = new GreetingFunction { name = "Hawk"; greeting = "Good day" }.message (5)

1	A required input property.
2	An optional input property with a default value.
3	An output property, calculated from the input properties.
4	result: `"Hello, Pigeon!"`
5	result: `"Good day, Hawk!"`

Tips

Despite the name, the pattern can also be applied using a module.
The CaaF pattern is especially compelling in cases where multiple outputs will be derived from the same set of inputs. Instead of defining multiple methods that accept the same parameters, a single class may be defined with multiple output properties.

In some cases, it may make sense to use CaaF in conjunction with output converters. This allows the "un-called" function instance to be used in place of the result data and enables amending the arguments to the function while still producing the desired output type and value, eg.:

greetPigeon: GreetingFunction|String = "こんばんは、鳩さん" (1)

greetHawk: GreetingFunction|String = new GreetingFunction { name = "Hawk" } (2)

farewellHawk = (greetHawk) {
  greeting = "Bye" (3)
}

output {
  renderer {
    converters {
      [GreetingFunction] = (it) -> it.message (4)
    }
  }
}

1	A fully custom greeting not using `GreetingFunction`.
2	result: `"Hi, Hawk!"`
3	result: `"Bye, Hawk!"`
4	Configuring a converter for `GreetingFunction` causes instances to be "evaluated" in the rendered output.

Multi-directional Functions

Pkl’s system of property default values and late binding enables using class-as-a-function to concisely express inverse and even circular relationships between properties. This allows the same property to be both input and output, depending on how the function type is used.

Using this technique entails declaring properties with default values derived from the other properties of the type in a cyclic fashion. Ordinarily, a circular data reference of this kind would result in a stack overflow error, but instantiating the type with the appropriate input(s) overridden with concrete values breaks the circular reference.

class Temperature {
  fahrenheit: Float = celsius * 9 / 5 + 32
  celsius: Float = kelvin - 273.15
  kelvin: Float = (fahrenheit - 32) / 9 * 5 + 273.15
}

fToK = new Temperature { fahrenheit = 72.0 }.kelvin
fToC = new Temperature { fahrenheit = 72.0 }.celsius
kToF = new Temperature { kelvin = 300.0 }.fahrenheit
kToC = new Temperature { kelvin = 300.0 }.celsius
cToF = new Temperature { celsius = 20.0 }.fahrenheit
cToK = new Temperature { celsius = 20.0 }.kelvin

Building Abstractions

The class-as-a-function pattern can be used to build abstraction layers that provide simple APIs resulting in more complex configurations. This is sometimes called "embedding" a class.

Kubernetes is an example of a system that requires a lot of configuration to use. Often, deploying applications in Kubernetes requires repeating very similar configurations with only names and a few values changed. Here is an example of a CaaF module that uses class embedding to build a simple but extensible abstraction for basic web services:

module SimpleApplication

import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/K8sResource.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/apps/v1/Deployment.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/core/v1/Service.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/networking/v1/Ingress.pkl"

// input properties:
/// Web application name
name: String

/// Container image tag
image: String

/// Application Pod replica count
replicas: Int32? = 1

/// HTTP listen port
port: UInt16 = 8080

/// URL Path to use for liveness checking
livenessPath: String? = "/livez"

/// URL Path to use for readiness checking
readinessPath: String? = "/readyz"

// output properties:
local app = this (1)

/// Kubernetes labels used for all output resources and selectors
labels: Mapping<String, String> = new { (2)
  ["app.kubernetes.io/name"] = name
}

/// Kuberetes [Deployment] that manages the application Pods.
deployment: Deployment = new { (3)
  metadata {
    name = app.name
    labels = app.labels
  }
  spec {
    replicas = app.replicas
    template {
      metadata {
        labels = app.labels
      }
      spec {
        containers {
          new {
            name = app.name
            image = app.image
            when (livenessPath != null) {
              livenessProbe {
                httpGet {
                  port = app.port
                  path = livenessPath
                }
              }
            }
            when (readinessPath != null) {
              readinessProbe {
                httpGet {
                  port = app.port
                  path = readinessPath
                }
              }
            }
          }
        }
      }
    }
  }
}

/// Kubernetes [Service] that provides a cluster-internal VIP for the application.
service: Service = new { (3)
  metadata {
    name = app.name
    labels = app.labels
  }
  spec {
    selector = app.labels
    ports {
      new {
        name = "http"
        port = app.port
      }
    }
  }
}

/// Kubernetes [Ingress] that exposes a VIP for the application outside the cluster.
ingress: Ingress = new { (3)
  metadata {
    name = app.name
    labels = app.labels
  }
  spec {
    defaultBackend {
      service {
        name = app.service?.metadata?.name!!
        port  {
          number = app.service.spec?.ports!![0].port
        }
      }
    }
  }
}

/// All Kubernetes resources needed to deploy the application.
resources: Listing<K8sResource> = new { (4)
  deployment
  service
  ingress
}

1	This "captures" the `SimpleApplication` instance so its properties can be unambiguously referred to.
2	The `labels` property is an "intermediary" property that serves as a customization point, it is calculated from inputs by default but is not itself an output.
3	The `deployment`, `service`, and `ingress` properties are the module’s primary output properties.
4	For convenience, the `resources` property combines all of the above outputs into a single `Listing`.

Notably, this example does not mark its output properties as fixed, which enables easy customization of these properties beyond what the module configures by default. Here are a few examples of using the SimpleApplication module:

import "SimpleApplication.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/K8sResource.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/networking/v1/NetworkPolicy.pkl"

/// The most basic [SimpleApplication] usage.
///
/// The application image is expected to listen on port 8080 and provide `/livez` and `/readyz` paths
app1: Listing<K8sResource> = new SimpleApplication {
  name = "app1"
  image = "myregistry/app1:latest"
}.resources

/// Usage of [SimpleApplication] with additional input properties overridden.
app2: Listing<K8sResource> = new SimpleApplication {
  name = "app2"
  image = "myregistry/app2:latest"
  replicas = 3
  port = 9090
  livenessPath = null
  readinessPath = "/healthz"
}.resources

/// Advanced [SimpleApplication] usage where output properties are amended.
///
/// This example amends [deployment] directly to set properties not exposed by [SimpleApplication]'s simple API.
/// It also amends [resources] to add an additional resource required specifically by this application.
app3: Listing<K8sResource> = new SimpleApplication {
  name = "app3"
  image = "myregistry/app3:latest"
  labels {
    ["app.kubernetes.io/instance"] = "\(name)-staging"
  }
  deployment {
    spec {
      template {
        spec {
          securityContext {
            runAsNonRoot = true
          }
          initContainers {
            new {
              name = "my-init-container"
              // ...
            }
          }
        }
      }
    }
  }
  resources {
    new NetworkPolicy {
      // ...
    }
  }
}.resources