@xylabs/express 4.3.14

package/src/middleware/standardResponses/jsonApi/index.ts

@@ -0,0 +1,5 @@
+export * from './error.ts'
+export * from './links.ts'
+export * from './relationship.ts'
+export * from './resourceIdentifier.ts'
+export * from './response.ts'

package/src/middleware/standardResponses/jsonApi/links.ts

@@ -0,0 +1,6 @@
+export interface HrefWithMeta {
+  href: string
+  meta: Record<string, unknown>
+}
+export type ApiLink = string | HrefWithMeta
+export type ApiLinks = Record<string, ApiLink>

package/src/middleware/standardResponses/jsonApi/relationship.ts

@@ -0,0 +1,43 @@
+import type { ApiResourceIdentifierObject } from './resourceIdentifier.ts'
+
+export interface IRelationshipSelfLink {
+  /**
+   * A link for the relationship itself (a "relationship link"). This link allows the client to directly manipulate the relationship.
+   * For example, removing an author through an article’s relationship URL would disconnect the person from the article without
+   * deleting the people resource itself. When fetched successfully, this link returns the linkage for the related resources as its primary data.
+   */
+  self: string
+}
+
+export interface IRelationshipRelatedLink {
+  /**
+   * A related resource link
+   */
+  related: string
+}
+
+export interface IRelationshipLinks {
+  links: IRelationshipRelatedLink | IRelationshipSelfLink
+}
+
+/**
+ * Resource linkage in a compound document allows a client to link together all of the included resource objects without having to GET any URLs via links.
+ * Resource linkage MUST be represented as one of the following:
+ *    • null for empty to-one relationships.
+ *    • an empty array ([]) for empty to-many relationships.
+ *    • a single resource identifier object for non-empty to-one relationships.
+ *    • an array of resource identifier objects for non-empty to-many relationships.
+ */
+export type ResourceLinkage = null | [] | ApiResourceIdentifierObject | ApiResourceIdentifierObject[]
+export interface IRelationshipData {
+  data: ResourceLinkage
+}
+
+export type RelationshipMeta = Record<string, unknown>
+
+/**
+ * The value of the relationships key MUST be an object (a "relationships object"). Members of the relationships object ("relationships")
+ * represent references from the resource object in which it’s defined to other resource objects.
+ * Relationships may be to-one or to-many.
+ */
+export type Relationship = IRelationshipLinks | IRelationshipData | RelationshipMeta

package/src/middleware/standardResponses/jsonApi/resourceIdentifier.ts

@@ -0,0 +1,15 @@
+/**
+ * Within a given API, each resource object's type and id pair MUST identify a single, unique resource.
+ * (The set of URIs controlled by a server, or multiple servers acting as one, constitute an API.)
+ */
+export interface ApiResourceIdentifierObject {
+  /**
+   * The id member is not required when the resource object originates at the client and represents a new resource to be created on the server.
+   */
+  id: string
+  /**
+   * The type member is used to describe resource objects that share common attributes and relationships.
+   * The values of type members MUST adhere to the same constraints as member names.
+   */
+  type: string
+}

package/src/middleware/standardResponses/jsonApi/response.ts

@@ -0,0 +1,49 @@
+/**
+ * Loosely following the JSON API 1.0 formats and conventions
+ * https://jsonapi.org/format/
+ */
+
+import type { ApiError } from './error.ts'
+import type { ApiLinks } from './links.ts'
+import type { Relationship } from './relationship.ts'
+import type { ApiResourceIdentifierObject } from './resourceIdentifier.ts'
+
+export interface ApiResourceObject extends ApiResourceIdentifierObject {
+  /**
+   * An attributes object representing some of the resource's data.
+   */
+  attributes?: Record<string, unknown>
+  /**
+   * A links object containing links related to the resource.
+   */
+  links?: ApiLinks
+  /**
+   * A meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.
+   */
+  meta?: Record<string, unknown>
+  /**
+   * A relationships object describing relationships between the resource and other JSON:API resources.
+   */
+  relationships?: Record<string, Relationship>
+}
+
+export interface JsonApi {
+  meta?: Record<string, unknown>
+  version?: '1.0' | '1.1'
+}
+
+export interface ApiResponseBase {
+  jsonapi?: JsonApi
+  links?: ApiLinks
+  meta?: Record<string, unknown>
+}
+
+export interface ApiDataResponse<T extends ApiResourceIdentifierObject> extends ApiResponseBase {
+  data: T
+  included?: ApiResourceObject[]
+}
+export interface ApiErrorResponse extends ApiResponseBase {
+  errors: ApiError[]
+}
+
+export type ApiResponse<T extends ApiResourceIdentifierObject> = ApiDataResponse<T> | ApiErrorResponse

package/src/middleware/standardResponses/standardErrors.ts

@@ -0,0 +1,25 @@
+import type {
+  NextFunction, Request, Response,
+} from 'express'
+
+import type { ExpressError } from '../../Model/index.ts'
+import type { ApiError } from './jsonApi/index.ts'
+
+export const standardErrors = (err: ExpressError, req: Request, res: Response, next: NextFunction) => {
+  if (!err) {
+    next(err)
+    return
+  }
+  console.error(err.message)
+  if (!err.statusCode) err.statusCode = 500
+
+  const error: ApiError = {
+    detail: err.message,
+    status: `${err.statusCode}`,
+    title: err.name,
+  }
+
+  res.status(err.statusCode).json(error)
+
+  next(err)
+}

package/src/middleware/standardResponses/standardResponses.ts

@@ -0,0 +1,23 @@
+import type { Request, Response } from 'express'
+import mung from 'express-mung'
+
+import { getResponseMetadata } from './getResponseMetadata.ts'
+
+/**
+ * Transforms each response to conform to the standard response format (compatible with JSON API)
+ * @param body The original request body
+ * @param _req The request
+ * @param res The response
+ * @returns The transformed response body
+ */
+export const transformResponse = (body: unknown, _req: Request, res: Response) => {
+  const meta = getResponseMetadata(res)
+  return { data: body, meta }
+}
+
+/**
+ * Connect middleware to enable the transform of all responses to match
+ * the standard response format (compatible with JSON API)
+ */
+
+export const standardResponses = mung.json(transformResponse, { mungError: false })

package/xy.config.ts

@@ -0,0 +1,10 @@
+import type { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
+const config: XyTsupConfig = {
+  compile: {
+    browser: {},
+    neutral: {},
+    node: { src: true },
+  },
+}
+
+export default config