@yangsaiyam/helper 1.1.0

package/README.md

@@ -0,0 +1,94 @@
+# korre-mapping
+
+Shared key-value mappings for Korre projects.
+
+## Install
+
+SSH:
+
+```bash
+pnpm add git+ssh://git@github.com:your-org/korre-mapping.git
+```
+
+HTTPS:
+
+```bash
+pnpm add github:your-org/korre-mapping
+```
+
+## Use
+
+```ts
+import { CAREER_LOCATION, getLabelByKey } from "@korre/mapping";
+
+const label = getLabelByKey(CAREER_LOCATION, 1);
+// KualaLumpur
+```
+
+```tsx
+import { CAREER_JOB_TYPE, getOptionByKey } from "@korre/mapping";
+
+type CareerCardProps = {
+  career: {
+    title: string;
+    jobType: number;
+  };
+};
+
+export default function CareerCard({ career }: CareerCardProps) {
+  const jobType = getOptionByKey(CAREER_JOB_TYPE, career.jobType);
+
+  return (
+    <div>
+      <h2>{career.title}</h2>
+      <p>{jobType?.value ?? "Unknown"}</p>
+    </div>
+  );
+}
+```
+
+## Structure
+
+```text
+src/
+├─ career/
+│  └─ index.ts
+├─ contact-form/
+│  └─ index.ts
+├─ files/
+│  └─ index.ts
+├─ shared/
+│  ├─ helpers.ts
+│  └─ types.ts
+└─ index.ts
+```
+
+## Exports
+
+- `CAREER_JOB_TYPE`
+- `CAREER_CATEGORY`
+- `CAREER_MODE`
+- `CAREER_LOCATION`
+- `CONTACT_FORM_ENQUIRY_TYPE`
+- `FILE_STATUS`
+- `FILE_ORIGIN`
+- `getOptionByKey`
+- `getLabelByKey`
+- `getI18nKeyByKey`
+- `toRecord`
+
+## Update mappings
+
+Update `src/index.ts`, then commit and push:
+
+```bash
+git add .
+git commit -m "update mappings"
+git push
+```
+
+In consuming repos:
+
+```bash
+pnpm update @korre/mapping
+```

package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@yangsaiyam/helper",
+  "version": "1.1.0",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/src/career/index.ts

@@ -0,0 +1,39 @@
+import type { MappingOption } from "../shared/types";
+
+export const CAREER_JOB_TYPE = [
+  { key: 1, value: "Full-time", i18nKey: "career.jobType.1" },
+  { key: 2, value: "Part-time", i18nKey: "career.jobType.2" },
+  { key: 3, value: "Contract", i18nKey: "career.jobType.3" },
+  { key: 4, value: "Internship", i18nKey: "career.jobType.4" },
+] as const satisfies readonly MappingOption[];
+
+export const CAREER_CATEGORY = [
+  { key: 1, value: "Engineering", i18nKey: "career.category.1" },
+  { key: 2, value: "Design", i18nKey: "career.category.2" },
+  { key: 3, value: "Product", i18nKey: "career.category.3" },
+  { key: 4, value: "Marketing", i18nKey: "career.category.4" },
+] as const satisfies readonly MappingOption[];
+
+export const CAREER_MODE = [
+  { key: 1, value: "On-site", i18nKey: "career.mode.1" },
+  { key: 2, value: "Remote", i18nKey: "career.mode.2" },
+  { key: 3, value: "Hybrid", i18nKey: "career.mode.3" },
+] as const satisfies readonly MappingOption[];
+
+export const CAREER_LOCATION = [
+  { key: 1, value: "KualaLumpur", i18nKey: "career.location.1" },
+  { key: 2, value: "Selangor", i18nKey: "career.location.2" },
+  { key: 3, value: "Johor", i18nKey: "career.location.3" },
+  { key: 4, value: "Penang", i18nKey: "career.location.4" },
+  { key: 5, value: "Sabah", i18nKey: "career.location.5" },
+  { key: 6, value: "Sarawak", i18nKey: "career.location.6" },
+  { key: 7, value: "NegeriSembilan", i18nKey: "career.location.7" },
+  { key: 8, value: "Kedah", i18nKey: "career.location.8" },
+  { key: 9, value: "Kelantan", i18nKey: "career.location.9" },
+  { key: 10, value: "Perak", i18nKey: "career.location.10" },
+  { key: 11, value: "Terengganu", i18nKey: "career.location.11" },
+  { key: 12, value: "Perlis", i18nKey: "career.location.12" },
+  { key: 13, value: "Melaka", i18nKey: "career.location.13" },
+  { key: 14, value: "Putrajaya", i18nKey: "career.location.14" },
+  { key: 15, value: "Labuan", i18nKey: "career.location.15" },
+] as const satisfies readonly MappingOption[];

package/src/contact-form/index.ts

@@ -0,0 +1,15 @@
+import type { MappingOption } from "../shared/types";
+
+export const CONTACT_FORM_ENQUIRY_TYPE = [
+  {
+    key: 1,
+    value: "Software Development",
+    i18nKey: "contactForm.enquiryType.1",
+  },
+  {
+    key: 2,
+    value: "Advertising Platform",
+    i18nKey: "contactForm.enquiryType.2",
+  },
+  { key: 3, value: "MCN Business", i18nKey: "contactForm.enquiryType.3" },
+] as const satisfies readonly MappingOption[];

package/src/files/index.ts

@@ -0,0 +1,11 @@
+import type { MappingOption } from "../shared/types";
+
+export const FILE_STATUS = [
+  { key: 1, value: "pending", i18nKey: "files.status.1" },
+  { key: 2, value: "submitted", i18nKey: "files.status.2" },
+] as const satisfies readonly MappingOption[];
+
+export const FILE_ORIGIN = [
+  { key: 1, value: "job applications", i18nKey: "files.origin.1" },
+  { key: 2, value: "submitted", i18nKey: "files.origin.2" },
+] as const satisfies readonly MappingOption[];

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./career";
+export * from "./contact-form";
+export * from "./files";
+export * from "./roles";
+export * from "./shared/helpers";
+export * from "./shared/types";

package/src/roles/index.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+
+import {
+  PERMISSION_I18N_KEY,
+  Permission,
+  ROLE,
+  ROLE_PERMISSIONS,
+  hasPermission,
+  normalizeRole,
+  permissionLabelKey,
+  roleLabelKey,
+  roleToId,
+} from "./index.ts";
+
+assert.equal(normalizeRole(0), "super-admin");
+assert.equal(normalizeRole("admin"), "admin");
+assert.equal(normalizeRole(2), "staff");
+assert.equal(normalizeRole("hr"), "hr");
+assert.equal(normalizeRole("unknown"), undefined);
+assert.equal(normalizeRole(undefined), undefined);
+
+assert.equal(roleToId("super-admin"), 0);
+assert.equal(roleToId("admin"), 1);
+assert.equal(roleToId("staff"), 2);
+assert.equal(roleToId("hr"), 3);
+assert.equal(roleToId("unknown"), undefined);
+
+assert.equal(roleLabelKey(0), "users.roleSuperAdmin");
+assert.equal(roleLabelKey("admin"), "users.roleAdmin");
+assert.equal(roleLabelKey(2), "users.roleStaff");
+assert.equal(roleLabelKey("hr"), "users.roleHr");
+assert.equal(roleLabelKey(undefined), "users.roleStaff");
+
+assert.deepEqual(ROLE[0], {
+  key: 0,
+  value: "super-admin",
+  i18nKey: "users.roleSuperAdmin",
+});
+assert.equal(ROLE[3]?.i18nKey, "users.roleHr");
+
+assert.equal(
+  PERMISSION_I18N_KEY[Permission.ALLOWED_EMAILS_READ],
+  "permissions.allowedEmailsRead",
+);
+assert.equal(
+  permissionLabelKey(Permission.CONTACT_FORM_DELETE),
+  "permissions.contactFormDelete",
+);
+
+assert.ok(ROLE_PERMISSIONS["super-admin"].includes(Permission.USERS_DELETE));
+assert.ok(ROLE_PERMISSIONS.admin.includes(Permission.CONTACT_FORM_DELETE));
+assert.ok(ROLE_PERMISSIONS.hr.includes(Permission.JOB_APPLICATIONS_READ));
+assert.deepEqual(ROLE_PERMISSIONS.staff, [Permission.CAREERS_READ]);
+
+assert.equal(hasPermission("super-admin", Permission.USERS_WRITE), true);
+assert.equal(hasPermission(1, Permission.USERS_WRITE), false);
+assert.equal(hasPermission("hr", Permission.CAREERS_WRITE), true);
+assert.equal(hasPermission("staff", Permission.CAREERS_WRITE), false);
+assert.equal(hasPermission(undefined, Permission.CAREERS_READ), false);

package/src/roles/index.ts

@@ -0,0 +1,144 @@
+import type { MappingOption } from "../shared/types";
+
+export type CanonicalRole = "super-admin" | "admin" | "hr" | "staff";
+export type RoleValue = CanonicalRole | number;
+export type RoleInput = RoleValue | string;
+
+export const ROLE = [
+  { key: 0, value: "super-admin", i18nKey: "users.roleSuperAdmin" },
+  { key: 1, value: "admin", i18nKey: "users.roleAdmin" },
+  { key: 2, value: "staff", i18nKey: "users.roleStaff" },
+  { key: 3, value: "hr", i18nKey: "users.roleHr" },
+] as const satisfies readonly MappingOption[];
+
+export function normalizeRole(
+  role: RoleInput | undefined,
+): CanonicalRole | undefined {
+  switch (role) {
+    case 0:
+    case "super-admin":
+      return "super-admin";
+    case 1:
+    case "admin":
+      return "admin";
+    case 2:
+    case "staff":
+      return "staff";
+    case 3:
+    case "hr":
+      return "hr";
+    default:
+      return undefined;
+  }
+}
+
+export function roleLabelKey(role: RoleInput | undefined): string {
+  switch (normalizeRole(role)) {
+    case "super-admin":
+      return "users.roleSuperAdmin";
+    case "admin":
+      return "users.roleAdmin";
+    case "hr":
+      return "users.roleHr";
+    case "staff":
+      return "users.roleStaff";
+    default:
+      return "users.roleStaff";
+  }
+}
+
+export function roleToId(role: RoleInput | undefined): number | undefined {
+  switch (normalizeRole(role)) {
+    case "super-admin":
+      return 0;
+    case "admin":
+      return 1;
+    case "staff":
+      return 2;
+    case "hr":
+      return 3;
+    default:
+      return undefined;
+  }
+}
+
+export const Permission = {
+  ALLOWED_EMAILS_READ: "allowed-emails:read",
+  ALLOWED_EMAILS_WRITE: "allowed-emails:write",
+  USERS_READ: "users:read",
+  USERS_WRITE: "users:write",
+  USERS_DELETE: "users:delete",
+  CAREERS_READ: "careers:read",
+  CAREERS_WRITE: "careers:write",
+  CAREERS_DELETE: "careers:delete",
+  CONTACT_FORM_READ: "contact-form:read",
+  CONTACT_FORM_DELETE: "contact-form:delete",
+  JOB_APPLICATIONS_READ: "job-applications:read",
+} as const;
+
+export type Permission = (typeof Permission)[keyof typeof Permission];
+
+export const PERMISSION_I18N_KEY: Record<Permission, string> = {
+  [Permission.ALLOWED_EMAILS_READ]: "permissions.allowedEmailsRead",
+  [Permission.ALLOWED_EMAILS_WRITE]: "permissions.allowedEmailsWrite",
+  [Permission.USERS_READ]: "permissions.usersRead",
+  [Permission.USERS_WRITE]: "permissions.usersWrite",
+  [Permission.USERS_DELETE]: "permissions.usersDelete",
+  [Permission.CAREERS_READ]: "permissions.careersRead",
+  [Permission.CAREERS_WRITE]: "permissions.careersWrite",
+  [Permission.CAREERS_DELETE]: "permissions.careersDelete",
+  [Permission.CONTACT_FORM_READ]: "permissions.contactFormRead",
+  [Permission.CONTACT_FORM_DELETE]: "permissions.contactFormDelete",
+  [Permission.JOB_APPLICATIONS_READ]: "permissions.jobApplicationsRead",
+};
+
+export const ROLE_PERMISSIONS: Record<CanonicalRole, Permission[]> = {
+  "super-admin": [
+    Permission.ALLOWED_EMAILS_READ,
+    Permission.ALLOWED_EMAILS_WRITE,
+    Permission.USERS_READ,
+    Permission.USERS_WRITE,
+    Permission.USERS_DELETE,
+    Permission.CAREERS_READ,
+    Permission.CAREERS_WRITE,
+    Permission.CAREERS_DELETE,
+    Permission.CONTACT_FORM_READ,
+    Permission.CONTACT_FORM_DELETE,
+    Permission.JOB_APPLICATIONS_READ,
+  ],
+  admin: [
+    Permission.ALLOWED_EMAILS_READ,
+    Permission.ALLOWED_EMAILS_WRITE,
+    Permission.USERS_READ,
+    Permission.CAREERS_READ,
+    Permission.CAREERS_WRITE,
+    Permission.CAREERS_DELETE,
+    Permission.CONTACT_FORM_READ,
+    Permission.CONTACT_FORM_DELETE,
+    Permission.JOB_APPLICATIONS_READ,
+  ],
+  hr: [
+    Permission.CAREERS_READ,
+    Permission.CAREERS_WRITE,
+    Permission.CAREERS_DELETE,
+    Permission.JOB_APPLICATIONS_READ,
+  ],
+  staff: [Permission.CAREERS_READ],
+};
+
+export function hasPermission(
+  role: RoleInput | undefined,
+  permission: Permission,
+): boolean {
+  const normalizedRole = normalizeRole(role);
+
+  if (!normalizedRole) {
+    return false;
+  }
+
+  return ROLE_PERMISSIONS[normalizedRole].includes(permission);
+}
+
+export function permissionLabelKey(permission: Permission): string {
+  return PERMISSION_I18N_KEY[permission];
+}

package/src/shared/helpers.ts

@@ -0,0 +1,34 @@
+import type { MappingOption } from "./types";
+
+export function getOptionByKey<T extends MappingOption>(
+  options: readonly T[],
+  key?: number | null,
+): T | undefined {
+  if (key === null || key === undefined) {
+    return undefined;
+  }
+
+  return options.find((option) => option.key === key);
+}
+
+export function getLabelByKey<T extends MappingOption>(
+  options: readonly T[],
+  key?: number | null,
+  fallback = "Unknown",
+): string {
+  return getOptionByKey(options, key)?.value ?? fallback;
+}
+
+export function getI18nKeyByKey<T extends MappingOption>(
+  options: readonly T[],
+  key?: number | null,
+  fallback = "unknown",
+): string {
+  return getOptionByKey(options, key)?.i18nKey ?? fallback;
+}
+
+export function toRecord<T extends MappingOption>(
+  options: readonly T[],
+): Record<number, string> {
+  return Object.fromEntries(options.map((option) => [option.key, option.value]));
+}

package/src/shared/types.ts

@@ -0,0 +1,5 @@
+export type MappingOption<K extends number = number> = {
+  key: K;
+  value: string;
+  i18nKey: string;
+};

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}