refactor: versioning and migration mechanism for public data structures (#3457)

Co-authored-by: jamesgeorge007 <jamesgeorge998001@gmail.com>

packages/hoppscotch-data/src/graphql/HoppGQLAuth.ts

@@ -1,43 +0,0 @@
-export type HoppGQLAuthNone = {
-  authType: "none"
-}
-
-export type HoppGQLAuthBasic = {
-  authType: "basic"
-
-  username: string
-  password: string
-}
-
-export type HoppGQLAuthBearer = {
-  authType: "bearer"
-
-  token: string
-}
-
-export type HoppGQLAuthOAuth2 = {
-  authType: "oauth-2"
-
-  token: string
-  oidcDiscoveryURL: string
-  authURL: string
-  accessTokenURL: string
-  clientID: string
-  scope: string
-}
-
-export type HoppGQLAuthAPIKey = {
-  authType: "api-key"
-
-  key: string
-  value: string
-  addTo: string
-}
-
-export type HoppGQLAuth = { authActive: boolean } & (
-  | HoppGQLAuthNone
-  | HoppGQLAuthBasic
-  | HoppGQLAuthBearer
-  | HoppGQLAuthOAuth2
-  | HoppGQLAuthAPIKey
-)

packages/hoppscotch-data/src/graphql/index.ts

@@ -1,51 +1,75 @@
-import { HoppGQLAuth } from "./HoppGQLAuth"
+import { InferredEntity, createVersionedEntity } from "verzod"
+import { z } from "zod"
+import V1_VERSION from "./v/1"
+import V2_VERSION from "./v/2"
 
-export * from "./HoppGQLAuth"
+export { GQLHeader } from "./v/1"
+export {
+  HoppGQLAuth,
+  HoppGQLAuthAPIKey,
+  HoppGQLAuthBasic,
+  HoppGQLAuthBearer,
+  HoppGQLAuthNone,
+  HoppGQLAuthOAuth2,
+} from "./v/2"
 
 export const GQL_REQ_SCHEMA_VERSION = 2
 
-export type GQLHeader = {
-  key: string
-  value: string
-  active: boolean
-}
+const versionedObject = z.object({
+  v: z.number(),
+})
 
-export type HoppGQLRequest = {
-  id?: string
-  v: number
-  name: string
-  url: string
-  headers: GQLHeader[]
-  query: string
-  variables: string
-  auth: HoppGQLAuth
-}
+export const HoppGQLRequest = createVersionedEntity({
+  latestVersion: 2,
+  versionMap: {
+    1: V1_VERSION,
+    2: V2_VERSION,
+  },
+  getVersion(x) {
+    const result = versionedObject.safeParse(x)
 
-export function translateToGQLRequest(x: any): HoppGQLRequest {
-  if (x.v && x.v === GQL_REQ_SCHEMA_VERSION) return x
+    return result.success ? result.data.v : null
+  },
+})
 
-  // Old request
-  const name = x.name ?? "Untitled"
-  const url = x.url ?? ""
-  const headers = x.headers ?? []
-  const query = x.query ?? ""
-  const variables = x.variables ?? []
-  const auth = x.auth ?? {
-    authType: "none",
-    authActive: true,
+export type HoppGQLRequest = InferredEntity<typeof HoppGQLRequest>
+
+const DEFAULT_QUERY = `
+query Request {
+  method
+  url
+  headers {
+    key
+    value
   }
+}`.trim()
 
+export function getDefaultGQLRequest(): HoppGQLRequest {
   return {
     v: GQL_REQ_SCHEMA_VERSION,
-    name,
-    url,
-    headers,
-    query,
-    variables,
-    auth
+    name: "Untitled",
+    url: "https://echo.hoppscotch.io/graphql",
+    headers: [],
+    variables: `
+{
+  "id": "1"
+}`.trim(),
+    query: DEFAULT_QUERY,
+    auth: {
+      authType: "none",
+      authActive: true,
+    },
   }
 }
 
+/**
+ * @deprecated This function is deprecated. Use `HoppGQLRequest` instead.
+ */
+export function translateToGQLRequest(x: unknown): HoppGQLRequest {
+  const result = HoppGQLRequest.safeParse(x)
+  return result.type === "ok" ? result.value : getDefaultGQLRequest()
+}
+
 export function makeGQLRequest(x: Omit<HoppGQLRequest, "v">): HoppGQLRequest {
   return {
     v: GQL_REQ_SCHEMA_VERSION,

packages/hoppscotch-data/src/graphql/v/1.ts

@@ -0,0 +1,24 @@
+import { z } from "zod"
+import { defineVersion } from "verzod"
+
+export const GQLHeader = z.object({
+  key: z.string(),
+  value: z.string(),
+  active: z.boolean()
+})
+
+export type GQLHeader = z.infer<typeof GQLHeader>
+
+export const V1_SCHEMA = z.object({
+  v: z.literal(1),
+  name: z.string(),
+  url: z.string(),
+  headers: z.array(GQLHeader),
+  query: z.string(),
+  variables: z.string(),
+})
+
+export default defineVersion({
+  initial: true,
+  schema: V1_SCHEMA
+})

packages/hoppscotch-data/src/graphql/v/2.ts

@@ -0,0 +1,91 @@
+import { z } from "zod"
+import { defineVersion } from "verzod"
+import { GQLHeader, V1_SCHEMA } from "./1"
+
+export const HoppGQLAuthNone = z.object({
+  authType: z.literal("none")
+})
+
+export type HoppGQLAuthNone = z.infer<typeof HoppGQLAuthNone>
+
+export const HoppGQLAuthBasic = z.object({
+  authType: z.literal("basic"),
+
+  username: z.string(),
+  password: z.string()
+})
+
+export type HoppGQLAuthBasic = z.infer<typeof HoppGQLAuthBasic>
+
+export const HoppGQLAuthBearer = z.object({
+  authType: z.literal("bearer"),
+
+  token: z.string()
+})
+
+export type HoppGQLAuthBearer = z.infer<typeof HoppGQLAuthBearer>
+
+export const HoppGQLAuthOAuth2 = z.object({
+  authType: z.literal("oauth-2"),
+
+  token: z.string(),
+  oidcDiscoveryURL: z.string(),
+  authURL: z.string(),
+  accessTokenURL: z.string(),
+  clientID: z.string(),
+  scope: z.string()
+})
+
+export type HoppGQLAuthOAuth2 = z.infer<typeof HoppGQLAuthOAuth2>
+
+export const HoppGQLAuthAPIKey = z.object({
+  authType: z.literal("api-key"),
+
+  key: z.string(),
+  value: z.string(),
+  addTo: z.string()
+})
+
+export type HoppGQLAuthAPIKey = z.infer<typeof HoppGQLAuthAPIKey>
+
+export const HoppGQLAuth = z.discriminatedUnion("authType", [
+  HoppGQLAuthNone,
+  HoppGQLAuthBasic,
+  HoppGQLAuthBearer,
+  HoppGQLAuthOAuth2,
+  HoppGQLAuthAPIKey
+]).and(
+  z.object({
+    authActive: z.boolean()
+  })
+)
+
+export type HoppGQLAuth = z.infer<typeof HoppGQLAuth>
+
+const V2_SCHEMA = z.object({
+  id: z.optional(z.string()),
+  v: z.literal(2),
+
+  name: z.string(),
+  url: z.string(),
+  headers: z.array(GQLHeader),
+  query: z.string(),
+  variables: z.string(),
+
+  auth: HoppGQLAuth
+})
+
+export default defineVersion({
+  initial: false,
+  schema: V2_SCHEMA,
+  up(old: z.infer<typeof V1_SCHEMA>) {
+    return <z.infer<typeof V2_SCHEMA>>{
+      ...old,
+      v: 2,
+      auth: {
+        authActive: true,
+        authType: "none",
+      }
+    }
+  }
+})