acrylblends 0.2.0 → 0.4.0

package/plugins/acryl-router/src/core/utils/headers.ts

@@ -0,0 +1,355 @@
+/**
+ * @module
+ * HTTP Headers utility.
+ */
+
+// note: https://www.iana.org/assignments/http-fields/http-fields.xhtml
+
+export type RequestHeader =
+  | 'A-IM'
+  | 'Accept'
+  | 'Accept-Additions'
+  | 'Accept-CH'
+  | 'Accept-Charset'
+  | 'Accept-Datetime'
+  | 'Accept-Encoding'
+  | 'Accept-Features'
+  | 'Accept-Language'
+  | 'Accept-Patch'
+  | 'Accept-Post'
+  | 'Accept-Query'
+  | 'Accept-Ranges'
+  | 'Accept-Signature'
+  | 'Access-Control'
+  | 'Access-Control-Allow-Credentials'
+  | 'Access-Control-Allow-Headers'
+  | 'Access-Control-Allow-Methods'
+  | 'Access-Control-Allow-Origin'
+  | 'Access-Control-Expose-Headers'
+  | 'Access-Control-Max-Age'
+  | 'Access-Control-Request-Headers'
+  | 'Access-Control-Request-Method'
+  | 'Activate-Storage-Access'
+  | 'Age'
+  | 'Allow'
+  | 'ALPN'
+  | 'Alt-Svc'
+  | 'Alt-Used'
+  | 'Alternates'
+  | 'AMP-Cache-Transform'
+  | 'Apply-To-Redirect-Ref'
+  | 'Authentication-Control'
+  | 'Authentication-Info'
+  | 'Authorization'
+  | 'Available-Dictionary'
+  | 'C-Ext'
+  | 'C-Man'
+  | 'C-Opt'
+  | 'C-PEP'
+  | 'C-PEP-Info'
+  | 'Cache-Control'
+  | 'Cache-Group-Invalidation'
+  | 'Cache-Groups'
+  | 'Cache-Status'
+  | 'Cal-Managed-ID'
+  | 'CalDAV-Timezones'
+  | 'Capsule-Protocol'
+  | 'CDN-Cache-Control'
+  | 'CDN-Loop'
+  | 'Cert-Not-After'
+  | 'Cert-Not-Before'
+  | 'Clear-Site-Data'
+  | 'Client-Cert'
+  | 'Client-Cert-Chain'
+  | 'Close'
+  | 'CMCD-Object'
+  | 'CMCD-Request'
+  | 'CMCD-Session'
+  | 'CMCD-Status'
+  | 'CMSD-Dynamic'
+  | 'CMSD-Static'
+  | 'Concealed-Auth-Export'
+  | 'Configuration-Context'
+  | 'Connection'
+  | 'Content-Base'
+  | 'Content-Digest'
+  | 'Content-Disposition'
+  | 'Content-Encoding'
+  | 'Content-ID'
+  | 'Content-Language'
+  | 'Content-Length'
+  | 'Content-Location'
+  | 'Content-MD5'
+  | 'Content-Range'
+  | 'Content-Script-Type'
+  | 'Content-Security-Policy'
+  | 'Content-Security-Policy-Report-Only'
+  | 'Content-Style-Type'
+  | 'Content-Type'
+  | 'Content-Version'
+  | 'Cookie'
+  | 'Cookie2'
+  | 'Cross-Origin-Embedder-Policy'
+  | 'Cross-Origin-Embedder-Policy-Report-Only'
+  | 'Cross-Origin-Opener-Policy'
+  | 'Cross-Origin-Opener-Policy-Report-Only'
+  | 'Cross-Origin-Resource-Policy'
+  | 'CTA-Common-Access-Token'
+  | 'DASL'
+  | 'Date'
+  | 'DAV'
+  | 'Default-Style'
+  | 'Delta-Base'
+  | 'Deprecation'
+  | 'Depth'
+  | 'Derived-From'
+  | 'Destination'
+  | 'Detached-JWS'
+  | 'Differential-ID'
+  | 'Dictionary-ID'
+  | 'Digest'
+  | 'DPoP'
+  | 'DPoP-Nonce'
+  | 'Early-Data'
+  | 'EDIINT-Features'
+  | 'ETag'
+  | 'Expect'
+  | 'Expect-CT'
+  | 'Expires'
+  | 'Ext'
+  | 'Forwarded'
+  | 'From'
+  | 'GetProfile'
+  | 'Hobareg'
+  | 'Host'
+  | 'HTTP2-Settings'
+  | 'If'
+  | 'If-Match'
+  | 'If-Modified-Since'
+  | 'If-None-Match'
+  | 'If-Range'
+  | 'If-Schedule-Tag-Match'
+  | 'If-Unmodified-Since'
+  | 'IM'
+  | 'Include-Referred-Token-Binding-ID'
+  | 'Incremental'
+  | 'Isolation'
+  | 'Keep-Alive'
+  | 'Label'
+  | 'Last-Event-ID'
+  | 'Last-Modified'
+  | 'Link'
+  | 'Link-Template'
+  | 'Location'
+  | 'Lock-Token'
+  | 'Man'
+  | 'Max-Forwards'
+  | 'Memento-Datetime'
+  | 'Meter'
+  | 'Method-Check'
+  | 'Method-Check-Expires'
+  | 'MIME-Version'
+  | 'Negotiate'
+  | 'NEL'
+  | 'OData-EntityId'
+  | 'OData-Isolation'
+  | 'OData-MaxVersion'
+  | 'OData-Version'
+  | 'Opt'
+  | 'Optional-WWW-Authenticate'
+  | 'Ordering-Type'
+  | 'Origin'
+  | 'Origin-Agent-Cluster'
+  | 'OSCORE'
+  | 'OSLC-Core-Version'
+  | 'Overwrite'
+  | 'P3P'
+  | 'PEP'
+  | 'PEP-Info'
+  | 'Permissions-Policy'
+  | 'PICS-Label'
+  | 'Ping-From'
+  | 'Ping-To'
+  | 'Position'
+  | 'Pragma'
+  | 'Prefer'
+  | 'Preference-Applied'
+  | 'Priority'
+  | 'ProfileObject'
+  | 'Protocol'
+  | 'Protocol-Info'
+  | 'Protocol-Query'
+  | 'Protocol-Request'
+  | 'Proxy-Authenticate'
+  | 'Proxy-Authentication-Info'
+  | 'Proxy-Authorization'
+  | 'Proxy-Features'
+  | 'Proxy-Instruction'
+  | 'Proxy-Status'
+  | 'Public'
+  | 'Public-Key-Pins'
+  | 'Public-Key-Pins-Report-Only'
+  | 'Range'
+  | 'Redirect-Ref'
+  | 'Referer'
+  | 'Referer-Root'
+  | 'Referrer-Policy'
+  | 'Refresh'
+  | 'Repeatability-Client-ID'
+  | 'Repeatability-First-Sent'
+  | 'Repeatability-Request-ID'
+  | 'Repeatability-Result'
+  | 'Replay-Nonce'
+  | 'Reporting-Endpoints'
+  | 'Repr-Digest'
+  | 'Retry-After'
+  | 'Safe'
+  | 'Schedule-Reply'
+  | 'Schedule-Tag'
+  | 'Sec-Fetch-Dest'
+  | 'Sec-Fetch-Mode'
+  | 'Sec-Fetch-Site'
+  | 'Sec-Fetch-Storage-Access'
+  | 'Sec-Fetch-User'
+  | 'Sec-GPC'
+  | 'Sec-Purpose'
+  | 'Sec-Token-Binding'
+  | 'Sec-WebSocket-Accept'
+  | 'Sec-WebSocket-Extensions'
+  | 'Sec-WebSocket-Key'
+  | 'Sec-WebSocket-Protocol'
+  | 'Sec-WebSocket-Version'
+  | 'Security-Scheme'
+  | 'Server'
+  | 'Server-Timing'
+  | 'Set-Cookie'
+  | 'Set-Cookie2'
+  | 'Set-Txn'
+  | 'SetProfile'
+  | 'Signature'
+  | 'Signature-Input'
+  | 'SLUG'
+  | 'SoapAction'
+  | 'Status-URI'
+  | 'Strict-Transport-Security'
+  | 'Sunset'
+  | 'Surrogate-Capability'
+  | 'Surrogate-Control'
+  | 'TCN'
+  | 'TE'
+  | 'Timeout'
+  | 'Timing-Allow-Origin'
+  | 'Topic'
+  | 'Traceparent'
+  | 'Tracestate'
+  | 'Trailer'
+  | 'Transfer-Encoding'
+  | 'TTL'
+  | 'Unencoded-Digest'
+  | 'Upgrade'
+  | 'Urgency'
+  | 'URI'
+  | 'Use-As-Dictionary'
+  | 'User-Agent'
+  | 'Variant-Vary'
+  | 'Vary'
+  | 'Via'
+  | 'Want-Content-Digest'
+  | 'Want-Digest'
+  | 'Want-Repr-Digest'
+  | 'Want-Unencoded-Digest'
+  | 'Warning'
+  | 'WWW-Authenticate'
+  | 'X-Content-Type-Options'
+  | 'X-Frame-Options'
+
+export type ResponseHeader =
+  | 'Accept-Query'
+  | 'Access-Control-Allow-Credentials'
+  | 'Access-Control-Allow-Headers'
+  | 'Access-Control-Allow-Methods'
+  | 'Access-Control-Allow-Origin'
+  | 'Access-Control-Expose-Headers'
+  | 'Access-Control-Max-Age'
+  | 'Activate-Storage-Access'
+  | 'Age'
+  | 'Allow'
+  | 'Cache-Control'
+  | 'Cache-Group-Invalidation'
+  | 'Cache-Groups'
+  | 'Clear-Site-Data'
+  | 'Content-Disposition'
+  | 'Content-Encoding'
+  | 'Content-Language'
+  | 'Content-Length'
+  | 'Content-Location'
+  | 'Content-Range'
+  | 'Content-Security-Policy'
+  | 'Content-Security-Policy-Report-Only'
+  | 'Content-Type'
+  | 'Cookie'
+  | 'Cross-Origin-Embedder-Policy'
+  | 'Cross-Origin-Opener-Policy'
+  | 'Cross-Origin-Resource-Policy'
+  | 'Date'
+  | 'ETag'
+  | 'Expires'
+  | 'Incremental'
+  | 'Last-Modified'
+  | 'Location'
+  | 'Permissions-Policy'
+  | 'Pragma'
+  | 'Retry-After'
+  | 'Save-Data'
+  | 'Sec-CH-Prefers-Color-Scheme'
+  | 'Sec-CH-Prefers-Reduced-Motion'
+  | 'Sec-CH-UA'
+  | 'Sec-CH-UA-Arch'
+  | 'Sec-CH-UA-Bitness'
+  | 'Sec-CH-UA-Form-Factor'
+  | 'Sec-CH-UA-Full-Version'
+  | 'Sec-CH-UA-Full-Version-List'
+  | 'Sec-CH-UA-Mobile'
+  | 'Sec-CH-UA-Model'
+  | 'Sec-CH-UA-Platform'
+  | 'Sec-CH-UA-Platform-Version'
+  | 'Sec-CH-UA-WoW64'
+  | 'Sec-Fetch-Dest'
+  | 'Sec-Fetch-Mode'
+  | 'Sec-Fetch-Site'
+  | 'Sec-Fetch-User'
+  | 'Sec-GPC'
+  | 'Server'
+  | 'Server-Timing'
+  | 'Service-Worker-Navigation-Preload'
+  | 'Set-Cookie'
+  | 'Set-Txn'
+  | 'Strict-Transport-Security'
+  | 'Timing-Allow-Origin'
+  | 'Trailer'
+  | 'Transfer-Encoding'
+  | 'Unencoded-Digest'
+  | 'Upgrade'
+  | 'Vary'
+  | 'Want-Unencoded-Digest'
+  | 'Warning'
+  | 'WWW-Authenticate'
+  | 'X-Content-Type-Options'
+  | 'X-DNS-Prefetch-Control'
+  | 'X-Frame-Options'
+  | 'X-Permitted-Cross-Domain-Policies'
+  | 'X-Powered-By'
+  | 'X-Robots-Tag'
+  | 'X-XSS-Protection'
+
+export type AcceptHeader =
+  | 'Accept'
+  | 'Accept-Charset'
+  | 'Accept-Encoding'
+  | 'Accept-Language'
+  | 'Accept-Patch'
+  | 'Accept-Post'
+  | 'Accept-Ranges'
+
+// note: `X-${string}` is deprecated
+export type CustomHeader = string & {}

package/plugins/acryl-router/src/core/utils/html.test.ts

@@ -0,0 +1,16 @@
+import { escapeToBuffer } from './html.ts'
+import type { StringBuffer } from './html.ts'
+
+describe('HTML utilities', () => {
+  describe('escapeToBuffer', () => {
+    it('Should escape special characters', () => {
+      let buffer: StringBuffer = ['']
+      escapeToBuffer('I <b>think</b> this is good.', buffer)
+      expect(buffer[0]).toBe('I &lt;b&gt;think&lt;/b&gt; this is good.')
+
+      buffer = ['']
+      escapeToBuffer('John "Johnny" Smith', buffer)
+      expect(buffer[0]).toBe('John &quot;Johnny&quot; Smith')
+    })
+  })
+})

package/plugins/acryl-router/src/core/utils/html.ts

@@ -0,0 +1,182 @@
+/**
+ * @module
+ * HTML utility.
+ */
+
+export const HtmlEscapedCallbackPhase = {
+  Stringify: 1,
+  BeforeStream: 2,
+  Stream: 3,
+} as const
+type HtmlEscapedCallbackOpts = {
+  buffer?: [string]
+  phase: (typeof HtmlEscapedCallbackPhase)[keyof typeof HtmlEscapedCallbackPhase]
+  context: Readonly<object> // An object unique to each JSX tree. This object is used as the WeakMap key.
+}
+export type HtmlEscapedCallback = (opts: HtmlEscapedCallbackOpts) => Promise<string> | undefined
+export type HtmlEscaped = {
+  isEscaped: true
+  callbacks?: HtmlEscapedCallback[]
+}
+export type HtmlEscapedString = string & HtmlEscaped
+
+/**
+ * StringBuffer contains string and Promise<string> alternately
+ * The length of the array will be odd, the odd numbered element will be a string,
+ * and the even numbered element will be a Promise<string>.
+ * When concatenating into a single string, it must be processed from the tail.
+ * @example
+ * [
+ *   'framework.',
+ *   Promise.resolve('ultra fast'),
+ *   'a ',
+ *   Promise.resolve('is '),
+ *   'App',
+ * ]
+ */
+export type StringBuffer = (string | Promise<string>)[]
+export type StringBufferWithCallbacks = StringBuffer & { callbacks: HtmlEscapedCallback[] }
+
+export const raw = (value: unknown, callbacks?: HtmlEscapedCallback[]): HtmlEscapedString => {
+  const escapedString = new String(value) as HtmlEscapedString
+  escapedString.isEscaped = true
+  escapedString.callbacks = callbacks
+
+  return escapedString
+}
+
+// The `escapeToBuffer` implementation is based on code from the MIT licensed `react-dom` package.
+// https://github.com/facebook/react/blob/main/packages/react-dom-bindings/src/server/escapeTextForBrowser.js
+
+const escapeRe = /[&<>'"]/
+
+export const stringBufferToString = async (
+  buffer: StringBuffer,
+  callbacks: HtmlEscapedCallback[] | undefined
+): Promise<HtmlEscapedString> => {
+  let str = ''
+  callbacks ||= []
+  const resolvedBuffer = await Promise.all(buffer)
+  for (let i = resolvedBuffer.length - 1; ; i--) {
+    str += resolvedBuffer[i]
+    i--
+    if (i < 0) {
+      break
+    }
+
+    let r = resolvedBuffer[i]
+    if (typeof r === 'object') {
+      callbacks.push(...((r as HtmlEscapedString).callbacks || []))
+    }
+
+    const isEscaped = (r as HtmlEscapedString).isEscaped
+    r = await (typeof r === 'object' ? (r as HtmlEscapedString).toString() : r)
+    if (typeof r === 'object') {
+      callbacks.push(...((r as HtmlEscapedString).callbacks || []))
+    }
+
+    if ((r as HtmlEscapedString).isEscaped ?? isEscaped) {
+      str += r
+    } else {
+      const buf = [str]
+      escapeToBuffer(r, buf)
+      str = buf[0]
+    }
+  }
+
+  return raw(str, callbacks)
+}
+
+export const escapeToBuffer = (str: string, buffer: StringBuffer): void => {
+  const match = str.search(escapeRe)
+  if (match === -1) {
+    buffer[0] += str
+    return
+  }
+
+  let escape
+  let index
+  let lastIndex = 0
+
+  for (index = match; index < str.length; index++) {
+    switch (str.charCodeAt(index)) {
+      case 34: // "
+        escape = '&quot;'
+        break
+      case 39: // '
+        escape = '&#39;'
+        break
+      case 38: // &
+        escape = '&amp;'
+        break
+      case 60: // <
+        escape = '&lt;'
+        break
+      case 62: // >
+        escape = '&gt;'
+        break
+      default:
+        continue
+    }
+
+    buffer[0] += str.substring(lastIndex, index) + escape
+    lastIndex = index + 1
+  }
+
+  buffer[0] += str.substring(lastIndex, index)
+}
+
+export const resolveCallbackSync = (str: string | HtmlEscapedString): string => {
+  const callbacks = (str as HtmlEscapedString).callbacks as HtmlEscapedCallback[]
+  if (!callbacks?.length) {
+    return str
+  }
+  const buffer: [string] = [str]
+  const context = {}
+
+  callbacks.forEach((c) => c({ phase: HtmlEscapedCallbackPhase.Stringify, buffer, context }))
+
+  return buffer[0]
+}
+
+export const resolveCallback = async (
+  str: string | HtmlEscapedString | Promise<string>,
+  phase: (typeof HtmlEscapedCallbackPhase)[keyof typeof HtmlEscapedCallbackPhase],
+  preserveCallbacks: boolean,
+  context: object,
+  buffer?: [string]
+): Promise<string> => {
+  if (typeof str === 'object' && !(str instanceof String)) {
+    if (!((str as unknown) instanceof Promise)) {
+      str = (str as unknown as string).toString() // HtmlEscapedString object to string
+    }
+    if ((str as string | Promise<string>) instanceof Promise) {
+      str = await (str as unknown as Promise<string>)
+    }
+  }
+
+  const callbacks = (str as HtmlEscapedString).callbacks as HtmlEscapedCallback[]
+  if (!callbacks?.length) {
+    return Promise.resolve(str)
+  }
+  if (buffer) {
+    buffer[0] += str
+  } else {
+    buffer = [str as string]
+  }
+
+  const resStr = Promise.all(callbacks.map((c) => c({ phase, buffer, context }))).then((res) =>
+    Promise.all(
+      res
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .filter<string>(Boolean as any)
+        .map((str) => resolveCallback(str, phase, false, context, buffer))
+    ).then(() => (buffer as [string])[0])
+  )
+
+  if (preserveCallbacks) {
+    return raw(await resStr, callbacks)
+  } else {
+    return resStr
+  }
+}

package/plugins/acryl-router/src/core/utils/http-status.ts

@@ -0,0 +1,72 @@
+/**
+ * @module
+ * HTTP Status utility.
+ */
+
+export type InfoStatusCode = 100 | 101 | 102 | 103
+export type SuccessStatusCode = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226
+export type DeprecatedStatusCode = 305 | 306
+export type RedirectStatusCode = 300 | 301 | 302 | 303 | 304 | DeprecatedStatusCode | 307 | 308
+export type ClientErrorStatusCode =
+  | 400
+  | 401
+  | 402
+  | 403
+  | 404
+  | 405
+  | 406
+  | 407
+  | 408
+  | 409
+  | 410
+  | 411
+  | 412
+  | 413
+  | 414
+  | 415
+  | 416
+  | 417
+  | 418
+  | 421
+  | 422
+  | 423
+  | 424
+  | 425
+  | 426
+  | 428
+  | 429
+  | 431
+  | 451
+export type ServerErrorStatusCode = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511
+
+/**
+ * `UnofficialStatusCode` can be used to specify an unofficial status code.
+ * @example
+ *
+ * ```ts
+ * app.get('/unknown', (c) => {
+ *   return c.text("Unknown Error", 520 as UnofficialStatusCode)
+ * })
+ * ```
+ */
+export type UnofficialStatusCode = -1
+
+/**
+ * @deprecated
+ * Use `UnofficialStatusCode` instead.
+ */
+export type UnOfficalStatusCode = UnofficialStatusCode
+
+/**
+ * If you want to use an unofficial status, use `UnofficialStatusCode`.
+ */
+export type StatusCode =
+  | InfoStatusCode
+  | SuccessStatusCode
+  | RedirectStatusCode
+  | ClientErrorStatusCode
+  | ServerErrorStatusCode
+  | UnofficialStatusCode
+
+export type ContentlessStatusCode = 101 | 204 | 205 | 304
+export type ContentfulStatusCode = Exclude<StatusCode, ContentlessStatusCode>