@nordcraft/core 1.0.0

package/src/api/api.ts

@@ -0,0 +1,414 @@
+import type { Formula, FormulaContext } from '../formula/formula'
+import { applyFormula } from '../formula/formula'
+import { omitKeys, sortObjectEntries } from '../utils/collections'
+import { hash } from '../utils/hash'
+import { isDefined, isObject, toBoolean } from '../utils/util'
+import type {
+  ApiBase,
+  ApiPerformance,
+  ApiRequest,
+  ComponentAPI,
+  LegacyComponentAPI,
+  ToddleRequestInit,
+} from './apiTypes'
+import { ApiMethod } from './apiTypes'
+import { LegacyToddleApi } from './LegacyToddleApi'
+import { ToddleApiV2 } from './ToddleApiV2'
+
+export const NON_BODY_RESPONSE_CODES = [101, 204, 205, 304]
+
+export const isLegacyApi = <Handler>(
+  api: ComponentAPI | LegacyToddleApi<Handler> | ToddleApiV2<Handler>,
+): api is LegacyComponentAPI | LegacyToddleApi<Handler> =>
+  api instanceof LegacyToddleApi ? true : !('version' in api)
+
+export const createApiRequest = <Handler>({
+  api,
+  formulaContext,
+  baseUrl,
+  defaultHeaders,
+}: {
+  api: ApiRequest | ToddleApiV2<Handler>
+  formulaContext: FormulaContext
+  baseUrl?: string
+  defaultHeaders: Headers | undefined
+}) => {
+  const url = getUrl(api, formulaContext, baseUrl)
+  const requestSettings = getRequestSettings({
+    api,
+    formulaContext,
+    defaultHeaders,
+  })
+
+  return { url, requestSettings }
+}
+
+export const getUrl = (
+  api: ApiBase,
+  formulaContext: FormulaContext,
+  baseUrl?: string,
+): URL => {
+  let urlPathname = ''
+  let urlQueryParams = new URLSearchParams()
+  let parsedUrl: URL | undefined
+  const url = applyFormula(api.url, formulaContext)
+  if (['string', 'number'].includes(typeof url)) {
+    const urlInput = typeof url === 'number' ? String(url) : url
+    try {
+      // Try to parse the URL to extract potential path and query parameters
+      parsedUrl = new URL(urlInput, baseUrl)
+      urlPathname = parsedUrl.pathname
+      urlQueryParams = parsedUrl.searchParams
+      // eslint-disable-next-line no-empty
+    } catch {}
+  }
+  const pathParams = getRequestPath(api.path, formulaContext)
+  // Combine potential path parameters from the url declaration with the actual path parameters
+  const path = `${urlPathname}${pathParams.length > 0 && !urlPathname.endsWith('/') ? '/' : ''}${pathParams}`
+  // Combine potential query parameters from the url declaration with the actual query parameters
+  const queryParams = new URLSearchParams([
+    ...urlQueryParams,
+    ...getRequestQueryParams(api.queryParams, formulaContext),
+  ])
+  const queryString =
+    [...queryParams.entries()].length > 0 ? `?${queryParams.toString()}` : ''
+  if (parsedUrl) {
+    const combinedUrl = new URL(parsedUrl.origin, baseUrl)
+    combinedUrl.pathname = path
+    combinedUrl.search = queryParams.toString()
+    return combinedUrl
+  } else {
+    return new URL(`${path}${queryString}`, baseUrl)
+  }
+}
+
+const HttpMethodsWithAllowedBody: ApiMethod[] = [
+  ApiMethod.POST,
+  ApiMethod.DELETE,
+  ApiMethod.PUT,
+  ApiMethod.PATCH,
+  ApiMethod.OPTIONS,
+]
+
+export const applyAbortSignal = (
+  api: ApiRequest,
+  requestSettings: RequestInit,
+  formulaContext: FormulaContext,
+) => {
+  if (api.timeout) {
+    const timeout = applyFormula(api.timeout.formula, formulaContext)
+    if (typeof timeout === 'number' && !Number.isNaN(timeout) && timeout > 0) {
+      requestSettings.signal = AbortSignal.timeout(timeout)
+    }
+  }
+}
+
+const getRequestSettings = ({
+  api,
+  formulaContext,
+  defaultHeaders,
+}: {
+  api: ApiRequest
+  formulaContext: FormulaContext
+  defaultHeaders: Headers | undefined
+}): ToddleRequestInit => {
+  const method = Object.values(ApiMethod).includes(api.method as ApiMethod)
+    ? (api.method as ApiMethod)
+    : ApiMethod.GET
+  const headers = getRequestHeaders({
+    apiHeaders: api.headers,
+    formulaContext,
+    defaultHeaders,
+  })
+  const body = getRequestBody({ api, formulaContext, headers, method })
+  if (headers.get('content-type') === 'multipart/form-data') {
+    headers.delete('content-type')
+  }
+
+  const requestSettings: ToddleRequestInit = {
+    method,
+    headers,
+    body,
+  }
+
+  applyAbortSignal(api, requestSettings, formulaContext)
+
+  return requestSettings
+}
+
+export const getRequestPath = (
+  path: ApiRequest['path'],
+  formulaContext: FormulaContext,
+): string =>
+  sortObjectEntries(path ?? {}, ([_, p]) => p.index)
+    .map(([_, p]) => applyFormula(p.formula, formulaContext))
+    .join('/')
+
+export const getRequestQueryParams = (
+  params: ApiRequest['queryParams'],
+  formulaContext: FormulaContext,
+): URLSearchParams => {
+  const queryParams = new URLSearchParams()
+  Object.entries(params ?? {}).forEach(([key, param]) => {
+    const enabled = isDefined(param.enabled)
+      ? applyFormula(param.enabled, formulaContext)
+      : true
+    if (!enabled) {
+      return
+    }
+
+    const value = applyFormula(param.formula, formulaContext)
+    if (!isDefined(value)) {
+      // Ignore null/undefined values
+      return
+    }
+    if (Array.isArray(value)) {
+      // Support encoding 1-dimensional arrays
+      value.forEach((v) => queryParams.append(key, String(v)))
+    } else if (isObject(value)) {
+      // Support encoding (nested) objects, but cast any non-object to a String
+      const encodeObject = (obj: Record<string, any>, prefix: string) => {
+        Object.entries(obj).forEach(([key, val]) => {
+          if (!Array.isArray(val) && isObject(val)) {
+            return encodeObject(val, `${prefix}[${key}]`)
+          } else {
+            queryParams.set(`${prefix}[${key}]`, String(val))
+          }
+        })
+      }
+      encodeObject(value, key)
+    } else {
+      queryParams.set(key, String(value))
+    }
+  })
+  return queryParams
+}
+
+export const getRequestHeaders = ({
+  apiHeaders,
+  formulaContext,
+  defaultHeaders,
+}: {
+  apiHeaders: ApiRequest['headers']
+  formulaContext: FormulaContext
+  defaultHeaders: Headers | undefined
+}) => {
+  const headers = new Headers(defaultHeaders)
+  Object.entries(apiHeaders ?? {}).forEach(([key, param]) => {
+    const enabled = isDefined(param.enabled)
+      ? applyFormula(param.enabled, formulaContext)
+      : true
+    if (enabled) {
+      const value = applyFormula(param.formula, formulaContext)
+      if (isDefined(value)) {
+        try {
+          headers.set(
+            key.trim(),
+            (typeof value === 'string' ? value : String(value)).trim(),
+          )
+          // eslint-disable-next-line no-empty
+        } catch {}
+      }
+    }
+  })
+  return headers
+}
+
+export const getBaseUrl = ({
+  origin,
+  url,
+}: {
+  origin: string
+  url?: string
+}) =>
+  !isDefined(url) || url === '' || url.startsWith('/') ? origin + url : url
+
+/**
+ * Calculate the hash of a Request object based on its properties
+ */
+export const requestHash = (url: URL, request: RequestInit) =>
+  hash(
+    JSON.stringify({
+      url: url.href,
+      method: request.method,
+      headers: omitKeys(
+        Object.fromEntries(Object.entries(request.headers ?? {})),
+        ['host', 'cookie'],
+      ),
+      body: request.body ?? null,
+    }),
+  )
+
+export const isApiError = ({
+  apiName,
+  response,
+  formulaContext,
+  errorFormula,
+  performance,
+}: {
+  apiName: string
+  response: {
+    ok: boolean
+    status?: number
+    headers?: Record<string, string> | null
+    body: unknown
+  }
+  formulaContext: FormulaContext
+  performance: ApiPerformance
+  errorFormula?: { formula: Formula } | null
+}) => {
+  const errorFormulaRes = errorFormula
+    ? applyFormula(errorFormula.formula, {
+        component: formulaContext.component,
+        package: formulaContext.package,
+        toddle: formulaContext.toddle,
+        data: {
+          Attributes: {},
+          Args: formulaContext.data.Args,
+          Apis: {
+            // The errorFormula will only have access to the data of the current API
+            [apiName]: {
+              isLoading: false,
+              data: response.body,
+              error: null,
+              response: {
+                status: response.status,
+                headers: response.headers,
+                performance,
+              },
+            },
+          },
+        },
+        env: formulaContext.env,
+      })
+    : null
+
+  if (errorFormulaRes === null || errorFormulaRes === undefined) {
+    return !response.ok
+  }
+  return toBoolean(errorFormulaRes)
+}
+
+const getRequestBody = ({
+  api,
+  formulaContext,
+  headers,
+  method,
+}: {
+  api: ApiRequest
+  formulaContext: FormulaContext
+  headers: Headers
+  method: ApiMethod
+}): FormData | string | undefined => {
+  if (!api.body || !HttpMethodsWithAllowedBody.includes(method)) {
+    return
+  }
+
+  const body = applyFormula(api.body, formulaContext)
+  if (!body) {
+    return
+  }
+  switch (headers.get('content-type')) {
+    case 'application/x-www-form-urlencoded': {
+      if (typeof body === 'object' && body !== null) {
+        return Object.entries(body)
+          .map(([key, value]) => {
+            if (Array.isArray(value)) {
+              return value
+                .map(
+                  (v) => `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,
+                )
+                .join('&')
+            } else {
+              return `${encodeURIComponent(key)}=${encodeURIComponent(
+                String(value),
+              )}`
+            }
+          })
+          .join('&')
+      }
+      return ''
+    }
+    case 'multipart/form-data': {
+      const formData = new FormData()
+      if (typeof body === 'object' && body !== null) {
+        Object.entries(body).forEach(([key, value]) => {
+          formData.set(key, value as string | Blob)
+        })
+      }
+      return formData
+    }
+    case 'text/plain':
+      return String(body)
+    default:
+      return JSON.stringify(body)
+  }
+}
+
+export const createApiEvent = (
+  eventName: 'message' | 'success' | 'failed',
+  detail: any,
+) => {
+  return new CustomEvent(eventName, {
+    detail,
+  })
+}
+
+const compareApiDependencies = <Handler>(
+  a: LegacyToddleApi<Handler> | ToddleApiV2<Handler>,
+  b: LegacyToddleApi<Handler> | ToddleApiV2<Handler>,
+) => {
+  const isADependentOnB = a.apiReferences.has(b.name)
+  const isBDependentOnA = b.apiReferences.has(a.name)
+  if (isADependentOnB === isBDependentOnA) {
+    return 0
+  }
+  // 1 means A goes last - hence B is evaluated before A
+  return isADependentOnB ? 1 : -1
+}
+
+export const sortApiObjects = <Handler>(
+  apis: Array<[string, ComponentAPI]>,
+) => {
+  const apiMap = new Map<
+    string,
+    LegacyToddleApi<Handler> | ToddleApiV2<Handler>
+  >()
+  const getApi = (apiObj: ComponentAPI, key: string) => {
+    let api = apiMap.get(key)
+    if (!api) {
+      api =
+        apiObj.version === 2
+          ? new ToddleApiV2<Handler>(
+              apiObj,
+              key,
+              // global formulas are not required for sorting
+              {
+                formulas: {},
+                packages: {},
+              },
+            )
+          : new LegacyToddleApi<Handler>(
+              apiObj,
+              key,
+              // global formulas are not required for sorting
+              {
+                formulas: {},
+                packages: {},
+              },
+            )
+      apiMap.set(key, api)
+    }
+    return api
+  }
+
+  return [...apis].sort(([aKey, aObj], [bKey, bObj]) => {
+    const a = getApi(aObj, aKey)
+    const b = getApi(bObj, bKey)
+    return compareApiDependencies(a, b)
+  })
+}
+
+export const sortApiEntries = <Handler>(
+  apis: Array<[string, LegacyToddleApi<Handler> | ToddleApiV2<Handler>]>,
+) => [...apis].sort(([_, a], [__, b]) => compareApiDependencies(a, b))

package/src/api/apiTypes.ts

@@ -0,0 +1,145 @@
+import type { EventModel } from '../component/component.types'
+import type { Formula } from '../formula/formula'
+import type { ToddleMetadata } from '../types'
+
+export type ComponentAPI = LegacyComponentAPI | ApiRequest
+
+export interface LegacyComponentAPI {
+  name: string
+  type: 'REST'
+  autoFetch?: Formula | null
+  url?: Formula
+  path?: { formula: Formula }[]
+  proxy?: boolean
+  queryParams?: Record<string, { name: string; formula: Formula }>
+  headers?: Record<string, Formula> | Formula
+  method?: 'GET' | 'POST' | 'DELETE' | 'PUT'
+  body?: Formula
+  auth?: {
+    type: 'Bearer id_token' | 'Bearer access_token'
+  }
+  throttle?: number | null
+  debounce?: number | null
+  onCompleted: EventModel | null
+  onFailed: EventModel | null
+  version?: never
+}
+
+export interface LegacyApiStatus {
+  data: unknown
+  isLoading: boolean
+  error: unknown
+  response?: never
+}
+
+export enum ApiMethod {
+  GET = 'GET',
+  POST = 'POST',
+  DELETE = 'DELETE',
+  PUT = 'PUT',
+  PATCH = 'PATCH',
+  HEAD = 'HEAD',
+  OPTIONS = 'OPTIONS',
+}
+
+export type RedirectStatusCode = 300 | 301 | 302 | 303 | 304 | 307 | 308
+
+export type ApiParserMode =
+  | 'auto'
+  | 'text'
+  | 'json'
+  | 'event-stream'
+  | 'json-stream'
+  | 'blob'
+
+export interface ApiBase extends ToddleMetadata {
+  url?: Formula
+  path?: Record<string, { formula: Formula; index: number }>
+  queryParams?: Record<
+    string,
+    // The enabled formula is used to determine if the query parameter should be included in the request or not
+    { formula: Formula; enabled?: Formula | null }
+  >
+}
+
+export interface ApiRequest extends ApiBase {
+  version: 2
+  name: string
+  type: 'http' | 'ws' // The structure for web sockets might look different
+  autoFetch?: Formula | null
+  headers?: Record<string, { formula: Formula; enabled?: Formula | null }>
+  method?: ApiMethod
+  body?: Formula
+  // inputs for an API request
+  inputs: Record<string, { formula: Formula | null }>
+  service?: string | null
+  servicePath?: string | null
+  server?: {
+    // We should only accept server side proxy requests if proxy is defined
+    proxy?: {
+      enabled: { formula: Formula }
+    } | null
+    ssr?: {
+      // We should only fetch a request server side during SSR if this is true
+      // it should probably be true by default for autofetch APIs
+      // During SSR we will only fetch autoFetch requests
+      enabled?: { formula: Formula } | null
+    }
+  }
+  client?: {
+    debounce?: { formula: Formula } | null
+    onCompleted?: EventModel | null
+    onFailed?: EventModel | null
+    onMessage?: EventModel | null
+    // parserMode is used to determine how the response should be handled
+    // auto: The response will be handled based on the content type of the response
+    // stream: The response will be handled as a stream
+    parserMode: ApiParserMode
+  }
+  // Shared logic for client/server 👇
+  // The user could distinguish using an environment
+  // variable e.g. IS_SERVER when they declare the formula
+
+  // Rules for redirecting the user to a different page
+  // These rules will run both on server+client - mostly used for 401 response -> 302 redirect
+  // We allow multiple rules since it makes it easier to setup multiple conditions/redirect locations
+  redirectRules?: Record<
+    string,
+    {
+      // The formula will receive the response from the server including a status code
+      // A redirect response will be returned if the formula returns a valid url
+      formula: Formula
+      // The status code used in the redirect response. Only relevant server side
+      statusCode?: RedirectStatusCode | null
+      index: number
+    }
+  > | null
+  // Formula for determining whether the response is an error or not. Receives the API response + status code/headers as input
+  // The response is considered an error if the formula returns true
+  // Default behavior is to check if the status code is 400 or higher
+  isError?: { formula: Formula } | null
+  // Formula for determining when the request should time out
+  timeout?: { formula: Formula } | null
+}
+
+export interface ApiStatus {
+  data: unknown
+  isLoading: boolean
+  error: unknown
+  response?: {
+    status?: number
+    headers?: Record<string, string> | null
+    performance?: ApiPerformance
+    debug?: null | unknown
+  }
+}
+
+export interface ApiPerformance {
+  requestStart: number | null
+  responseStart: number | null
+  responseEnd: number | null
+}
+
+export interface ToddleRequestInit extends RequestInit {
+  headers: Headers
+}

package/src/api/headers.ts

@@ -0,0 +1,41 @@
+/**
+ * Checks if a header is a json (content-type) header
+ * Also supports edge cases like application/vnd.api+json and application/vnd.contentful.delivery.v1+json
+ * See https://jsonapi.org/#mime-types
+ */
+export const isJsonHeader = (header?: string | null) => {
+  if (typeof header !== 'string') {
+    return false
+  }
+  return /^application\/(json|.*\+json)/.test(header)
+}
+
+export const isTextHeader = (header?: string | null) => {
+  if (typeof header !== 'string') {
+    return false
+  }
+  return /^(text\/|application\/x-www-form-urlencoded|application\/(xml|.*\+xml))/.test(
+    header,
+  )
+}
+
+export const isEventStreamHeader = (header?: string | null) => {
+  if (typeof header !== 'string') {
+    return false
+  }
+  return /^text\/event-stream/.test(header)
+}
+
+export const isJsonStreamHeader = (header?: string | null) => {
+  if (typeof header !== 'string') {
+    return false
+  }
+  return /^(application\/stream\+json|application\/x-ndjson)/.test(header)
+}
+
+export const isImageHeader = (header?: string | null) => {
+  if (typeof header !== 'string') {
+    return false
+  }
+  return /^image\//.test(header)
+}

package/src/api/template.ts

@@ -0,0 +1,10 @@
+export const STRING_TEMPLATE = (
+  type: keyof typeof templateTypes,
+  name: string,
+) => {
+  return `{{ ${templateTypes[type]}.${name} }}`
+}
+
+const templateTypes = {
+  cookies: 'cookies',
+}

package/src/component/ToddleComponent.actionReferences.test.ts

@@ -0,0 +1,75 @@
+import { ToddleComponent } from './ToddleComponent'
+
+describe('ToddleComponent.actionReferences', () => {
+  test('it return custom actions used in the component', () => {
+    const demo = new ToddleComponent({
+      component: {
+        name: 'demo',
+        apis: {},
+        attributes: {},
+        nodes: {},
+        variables: {},
+        workflows: {
+          '7XLoA3': {
+            name: 'my-workflow',
+            actions: [
+              {
+                type: 'Custom',
+                name: 'MyCustomAction',
+              },
+              {
+                name: 'MyLegacyCustomAction',
+              },
+            ],
+            parameters: [],
+          },
+        },
+      },
+      getComponent: () => undefined,
+      packageName: 'demo',
+      globalFormulas: { formulas: {}, packages: {} },
+    })
+    const actions = Array.from(demo.actionReferences)
+    expect(actions).toEqual(['MyCustomAction', 'MyLegacyCustomAction'])
+  })
+  test('it should not include non-custom actions', () => {
+    const demo = new ToddleComponent({
+      component: {
+        name: 'demo',
+        apis: {},
+        attributes: {},
+        nodes: {},
+        variables: {},
+        workflows: {
+          '7XLoA3': {
+            name: 'my-workflow',
+            actions: [
+              {
+                type: 'SetVariable',
+                data: {
+                  type: 'value',
+                  value: 'Hello World',
+                },
+                variable: 'my-variable',
+              },
+              {
+                type: 'TriggerEvent',
+                event: 'my-event',
+                data: {
+                  type: 'value',
+                  value: 'Hello World',
+                },
+              },
+            ],
+            parameters: [],
+          },
+        },
+      },
+      getComponent: () => undefined,
+      packageName: 'demo',
+      globalFormulas: { formulas: {}, packages: {} },
+    })
+    const actions = Array.from(demo.actionReferences)
+    expect(actions).toEqual([])
+  })
+})