feat: add draft version support and update emoji version schema

.gitignore

@@ -1,2 +1,3 @@
 node_modules
 .wrangler
+dist

src/routes/v1_categories.openapi.ts

@@ -1,29 +1,30 @@
 import { createRoute, z } from "@hono/zod-openapi";
-import { ApiErrorSchema, EmojiVersion } from "../schemas";
+import { ApiErrorSchema } from "../schemas";
 
+const VERSION_PATH_PARAMETER = {
+  in: "path" as const,
+  name: "version",
+  required: true,
+  example: "latest",
+  schema: {
+    type: "string" as const,
+  },
+};
 export const ALL_CATEGORIES_ROUTE = createRoute({
   method: "get",
   path: "/",
   tags: ["Categories"],
   parameters: [
-    {
-      in: "path",
-      name: "version",
-      required: true,
-      example: "latest",
-      schema: {
-        type: "string",
-      },
-    },
+    VERSION_PATH_PARAMETER,
   ],
   responses: {
     200: {
       content: {
         "application/json": {
-          schema: z.array(EmojiVersion),
+          schema: z.array(z.object({})),
         },
       },
-      description: "Retrieve a list of all emoji versions available",
+      description: "Retrieve a list of all emoji categories available for the specified version",
     },
     500: {
       content: {
@@ -41,10 +42,12 @@ export const GET_CATEGORY_ROUTE = createRoute({
   path: "/{category}",
   tags: ["Categories"],
   parameters: [
+    VERSION_PATH_PARAMETER,
     {
       in: "path",
-      name: "version",
+      name: "category",
       required: true,
+      example: "smileys",
       schema: {
         type: "string",
       },
@@ -54,10 +57,10 @@ export const GET_CATEGORY_ROUTE = createRoute({
     200: {
       content: {
         "application/json": {
-          schema: z.array(EmojiVersion),
+          schema: z.object({}),
         },
       },
-      description: "Retrieve a list of all emoji versions available",
+      description: "Retrieve the information for the specified emoji category",
     },
     500: {
       content: {

src/routes/v1_categories.ts

@@ -14,18 +14,26 @@ V1_CATEGORIES_ROUTER.use(async (c, next) => {
 
   const availableVersions = await getAvailableVersions();
 
-  if (!availableVersions.includes(version) && version !== "latest") {
-    return createError(c, 400, "invalid version");
+  if (version !== "latest" && !availableVersions.some((v) => v.emoji_version === version)) {
+    return createError(c, 404, "version not found");
   }
 
   await next();
 });
 
 V1_CATEGORIES_ROUTER.openapi(ALL_CATEGORIES_ROUTE, async (c) => {
-  const _version = c.req.param("version");
+  const version = c.req.param("version");
+
+  const res = await fetch(`https://raw.githubusercontent.com/mojisdev/emoji-data/refs/heads/main/data/v${version}/groups.json`);
+
+  if (!res.ok) {
+    return createError(c, 500, "failed to fetch categories");
+  }
+
+  const categories = await res.json();
 
   return c.json(
-    [],
+    categories as [],
     200,
   );
 });

src/routes/v1_versions.openapi.ts

@@ -1,15 +1,29 @@
 import { createRoute, z } from "@hono/zod-openapi";
-import { ApiErrorSchema, EmojiVersion } from "../schemas";
+import { ApiErrorSchema, EmojiVersionSchema } from "../schemas";
+
+const DRAFT_PARAMETER = {
+  in: "query" as const,
+  name: "draft",
+  required: false,
+  description: "Whether to include draft versions",
+  schema: {
+    type: "string" as const,
+    enum: ["true", "false"],
+  },
+};
 
 export const ALL_EMOJI_VERSIONS_ROUTE = createRoute({
   method: "get",
   path: "/",
   tags: ["Versions"],
+  parameters: [
+    DRAFT_PARAMETER,
+  ],
   responses: {
     200: {
       content: {
         "application/json": {
-          schema: z.array(EmojiVersion),
+          schema: z.array(EmojiVersionSchema),
         },
       },
       description: "Retrieve a list of all emoji versions available",
@@ -29,14 +43,49 @@ export const LATEST_EMOJI_VERSIONS_ROUTE = createRoute({
   method: "get",
   path: "/latest",
   tags: ["Versions"],
+  parameters: [
+    DRAFT_PARAMETER,
+  ],
   responses: {
     200: {
       content: {
         "application/json": {
-          schema: z.array(EmojiVersion),
+          schema: EmojiVersionSchema,
         },
       },
-      description: "Retrieve a list of all emoji versions available",
+      description: "Retrieve the latest emoji version available",
+    },
+    500: {
+      content: {
+        "application/json": {
+          schema: ApiErrorSchema,
+        },
+      },
+      description: "Internal Server Error",
+    },
+  },
+});
+
+export const DRAFT_EMOJI_VERSIONS_ROUTE = createRoute({
+  method: "get",
+  path: "/draft",
+  tags: ["Versions"],
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: EmojiVersionSchema,
+        },
+      },
+      description: "Retrieve the latest draft emoji version available",
+    },
+    404: {
+      content: {
+        "application/json": {
+          schema: ApiErrorSchema,
+        },
+      },
+      description: "No draft versions available",
     },
     500: {
       content: {

src/routes/v1_versions.ts

@@ -1,39 +1,56 @@
 import type { HonoContext } from "../types";
 import { OpenAPIHono } from "@hono/zod-openapi";
-import { EMOJI_LOCK_SCHEMA } from "../schemas";
-import { createError, getCachedVersions } from "../utils";
-import { ALL_EMOJI_VERSIONS_ROUTE, LATEST_EMOJI_VERSIONS_ROUTE } from "./v1_versions.openapi";
+import { createError, getAvailableVersions } from "../utils";
+import { ALL_EMOJI_VERSIONS_ROUTE, DRAFT_EMOJI_VERSIONS_ROUTE, LATEST_EMOJI_VERSIONS_ROUTE } from "./v1_versions.openapi";
 
 export const V1_VERSIONS_ROUTER = new OpenAPIHono<HonoContext>().basePath("/api/v1/versions");
 
 V1_VERSIONS_ROUTER.openapi(ALL_EMOJI_VERSIONS_ROUTE, async (c) => {
   try {
-    const versions = await getCachedVersions();
-    return c.json(versions.map((version) => ({ version })), 200);
+    const draft = c.req.query("draft");
+
+    let versions = await getAvailableVersions();
+
+    if (draft === "true") {
+      versions = versions.filter((version) => !version.draft);
+    }
+
+    return c.json(versions, 200);
   } catch {
     return createError(c, 500, "failed to fetch emoji data");
   }
 });
 
 V1_VERSIONS_ROUTER.openapi(LATEST_EMOJI_VERSIONS_ROUTE, async (c) => {
-  const res = await fetch("https://raw.githubusercontent.com/mojisdev/emoji-data/refs/heads/main/emojis.lock");
+  try {
+    const draft = c.req.query("draft");
+
+    let versions = await getAvailableVersions();
+
+    if (draft === "true") {
+      versions = versions.filter((version) => !version.draft);
+    }
+
+    if (versions[0] == null) {
+      return createError(c, 500, "failed to fetch emoji data");
+    }
 
-  if (!res.ok) {
+    return c.json(versions[0], 200);
+  } catch {
     return createError(c, 500, "failed to fetch emoji data");
   }
+});
 
-  const data = await res.json();
+V1_VERSIONS_ROUTER.openapi(DRAFT_EMOJI_VERSIONS_ROUTE, async (c) => {
+  try {
+    const versions = (await getAvailableVersions()).filter((version) => version.draft);
 
-  const result = EMOJI_LOCK_SCHEMA.safeParse(data);
+    if (versions[0] == null) {
+      return createError(c, 404, "no draft versions available");
+    }
 
-  if (!result.success) {
-    return createError(c, 500, "invalid emoji data schema");
+    return c.json(versions[0], 200);
+  } catch {
+    return createError(c, 500, "failed to fetch emoji data");
   }
-
-  return c.json(
-    result.data.versions.map((version) => ({
-      version: version.emoji_version,
-    })),
-    200,
-  );
 });

src/schemas.ts

@@ -1,10 +1,18 @@
 import { z } from "@hono/zod-openapi";
 
-export const EmojiVersion = z.object({
-  version: z.string().openapi({
+export const EmojiVersionSchema = z.object({
+  draft: z.boolean().openapi({
+    description: "Whether the version is a draft",
+    example: false,
+  }),
+  emoji_version: z.string().nullable().openapi({
     description: "The emoji version",
     example: "16.0",
   }),
+  unicode_version: z.string().nullable().openapi({
+    description: "The Unicode version that corresponds to the emoji version",
+    example: "14.0",
+  }),
 });
 
 export const ApiErrorSchema = z.object({
@@ -25,7 +33,11 @@ export const ApiErrorSchema = z.object({
 });
 
 export const EMOJI_LOCK_SCHEMA = z.object({
-  versions: z.array(z.object({
-    emoji_version: z.string(),
-  })),
+  versions: z.array(
+    z.object({
+      emoji_version: z.string().nullable(),
+      unicode_version: z.string().nullable(),
+      draft: z.boolean(),
+    }),
+  ),
 });

src/types.ts

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import type { ApiErrorSchema } from "./schemas";
+import type { ApiErrorSchema, EMOJI_LOCK_SCHEMA, EmojiVersionSchema } from "./schemas";
 
 export interface HonoContext {
   Bindings: {
@@ -11,3 +11,5 @@ export interface HonoContext {
 export type HonoBindings = HonoContext["Bindings"];
 
 export type ApiError = z.infer<typeof ApiErrorSchema>;
+export type EmojiLock = z.infer<typeof EMOJI_LOCK_SCHEMA>;
+export type EmojiVersion = z.infer<typeof EmojiVersionSchema>;

src/utils.ts

@@ -1,6 +1,7 @@
 import type { Context } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
-import type { ApiError } from "./types";
+import type { ApiError, EmojiLock } from "./types";
+import { EMOJI_LOCK_SCHEMA } from "./schemas";
 
 export function createError<TCtx extends Context, TStatus extends ContentfulStatusCode>(ctx: TCtx, status: TStatus, message: string) {
   const url = new URL(ctx.req.url);
@@ -14,29 +15,7 @@ export function createError<TCtx extends Context, TStatus extends ContentfulStat
   });
 }
 
-const CACHE_TTL = 60 * 60;
-
-export async function getCachedVersions(): Promise<string[]> {
-  const cache = await caches.open("emoji-versions");
-  const cacheKey = "versions";
-
-  let response = await cache.match(cacheKey);
-
-  if (!response) {
-    const versions = await getAvailableVersions();
-    response = new Response(JSON.stringify(versions), {
-      headers: {
-        "Cache-Control": `public, max-age=${CACHE_TTL}`,
-        "Content-Type": "application/json",
-      },
-    });
-    await cache.put(cacheKey, response.clone());
-  }
-
-  return JSON.parse(await response.text());
-}
-
-export async function getAvailableVersions(): Promise<string[]> {
+export async function getAvailableVersions(): Promise<EmojiLock["versions"]> {
   const res = await fetch("https://raw.githubusercontent.com/mojisdev/emoji-data/refs/heads/main/emojis.lock");
 
   if (!res.ok) {
@@ -45,17 +24,11 @@ export async function getAvailableVersions(): Promise<string[]> {
 
   const data = await res.json();
 
-  if (
-    data == null
-    || typeof data !== "object"
-    || !("versions" in data)
-    || !Array.isArray(data.versions)
-    || data.versions.some((version: any) => typeof version !== "object"
-      || !("emoji_version" in version)
-      || typeof version.emoji_version !== "string")
-  ) {
+  const result = EMOJI_LOCK_SCHEMA.safeParse(data);
+
+  if (!result.success) {
     throw new Error("invalid emoji data schema");
   }
 
-  return data.versions.map((version) => version.emoji_version);
+  return result.data.versions;
 }

test/index.test.ts

@@ -7,7 +7,7 @@ import { expect, it } from "vitest";
 import worker from "../src";
 
 it("respond with a 404", async () => {
-  const request = new Request("https://mojis.dev/not-found");
+  const request = new Request("https://api.mojis.dev/not-found");
   const ctx = createExecutionContext();
   const response = await worker.fetch(request, env, ctx);
   await waitOnExecutionContext(ctx);