typed_enums 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feccb1b7155c9c0bce08aca4c171c1368f9a07082962903378e925eede8087e7
-  data.tar.gz: ce34f0912b5fa25ea49e3187798b81f776bfd2b755ca4284a466659fd4639378
+  metadata.gz: 367406f60e95f76e1988c8cac92abf1bda727ca2362f0621c44388b2980a0c7f
+  data.tar.gz: be9c334bf39848c1451396a9999d718fb0cdf49480b147496c0e6cc6dcdbd9cb
 SHA512:
-  metadata.gz: 48c3acf6c06bd274037335c9989e8021dbd3128dc65d5386699135caeea03b9ef4608fe9abd3faca189af1cc355efc0e74dc754502540a95885ba544dea5f1f3
-  data.tar.gz: 7f1e5519b3742de53309e81cdc28f5b70ee25e5e34ce897bcd7d13d51bffd346962d256cb6aa2d2ab4ce22eafb6ee396d03bd5ee95bef7f1e70b6019f7333b44
+  metadata.gz: de4d1b59436e751875dff36e7ef0b2bc48618be1c1bbeb39676b8c023bad3017e48fbbe275a2c5a9a1c1f6c7953fac1baa40537a57260ec6b2278220de7f3bd7
+  data.tar.gz: 865b6b918499d80d66a6ed4c70c6fc59ed50709e3abda6509ab9053718ce6b8944dce2d703015a372320d396e1880754121aa336188bb3d6ec2a3a9004fc147b

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0
+
+### Breaking
+
+- Generated runtime enum exports now end in `Enums` to avoid collisions with serializer-generated model names. Update imports and usages such as `Task` to `TaskEnums`; TypeScript enum type aliases such as `TaskWorkPriority` are unchanged.
+
 ## 0.1.0
 
 - Initial implementation of Active Record enum scanning and TypeScript generation.

data/README.md

@@ -1,5 +1,7 @@
 # typed_enums
 
+[![Gem Version](https://badge.fury.io/rb/typed_enums.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/typed_enums)
+
 Use Rails enums in JavaScript and TypeScript without duplicating option lists.
 
 `typed_enums` is a Rails enum generator for JavaScript and TypeScript frontends. It exports Active Record enums to JavaScript constants and TypeScript declaration types, giving any frontend a Rails-like way to consume enum values.
@@ -56,9 +58,9 @@ end
 The generated JavaScript can be imported from the generated module:
 
 ```ts
-import { Task } from "@/lib/enums";
+import { TaskEnums } from "@/lib/enums";
 
-Task.workPriorities;
+TaskEnums.workPriorities;
 ```
 
 ## Generated JavaScript
@@ -69,7 +71,7 @@ The gem writes one JavaScript module containing every model enum:
 // AUTO-GENERATED BY typed_enums. DO NOT EDIT.
 // enum-schema-sha256: abc123
 
-export const Task = {
+export const TaskEnums = {
   workPriorities: ["priority_1", "priority_2", "priority_3", "priority_4"],
 };
 ```
@@ -80,16 +82,30 @@ It also writes `enums.d.ts` for TypeScript users:
 // AUTO-GENERATED BY typed_enums. DO NOT EDIT.
 // enum-schema-sha256: abc123
 
-export declare const Task: {
+export declare const TaskEnums: {
   readonly workPriorities: readonly ["priority_1", "priority_2", "priority_3", "priority_4"];
 };
 
-export type TaskWorkPriority = (typeof Task.workPriorities)[number];
+export type TaskWorkPriority = (typeof TaskEnums.workPriorities)[number];
+```
+
+## Upgrading to 0.2.0
+
+**Breaking change:** generated runtime exports now end in `Enums` so they can coexist with serializer-generated model names. Update imports and usages from `Task` to `TaskEnums`; enum type aliases, such as `TaskWorkPriority`, are unchanged.
+
+```ts
+// Before 0.2.0
+import { Task } from "@/lib/enums";
+Task.workPriorities;
+
+// 0.2.0 and later
+import { TaskEnums } from "@/lib/enums";
+TaskEnums.workPriorities;
 ```
 
 ## Naming
 
-Rails exposes enum mappings through pluralized methods, such as `Task.work_priorities`. `typed_enums` mirrors that convention in camelCase:
+Each runtime export uses the flattened model name with an `Enums` suffix, such as `TaskEnums` or `AdminTaskEnums`. Rails enum mappings remain pluralized and camel-cased, such as `Task.work_priorities` becoming `TaskEnums.workPriorities`:
 
 | Rails enum attribute | Rails mapping method | TypeScript property | TypeScript type |
 | --- | --- | --- | --- |
@@ -104,7 +120,7 @@ This naming is intentionally not configurable in v1.
 ## Type Usage
 
 ```ts
-import { Task, type TaskWorkPriority } from "@/lib/enums";
+import { TaskEnums, type TaskWorkPriority } from "@/lib/enums";
 
 function setPriority(priority: TaskWorkPriority) {
   return priority;
@@ -114,20 +130,104 @@ function setPriority(priority: TaskWorkPriority) {
 ## React
 
 ```tsx
-import { Task, type TaskWorkPriority } from "@/lib/enums";
+import { useId, useState, type FormEvent } from "react";
+import { TaskEnums, type TaskWorkPriority } from "@/lib/enums";
 
-export function PrioritySelect(props: {
-  value: TaskWorkPriority;
-  onChange: (value: TaskWorkPriority) => void;
+type TaskRecord = {
+  id: number;
+  workPriority: TaskWorkPriority;
+};
+
+type UpdateTaskPriorityParams = {
+  work_priority: TaskWorkPriority;
+};
+
+export function EditTaskPriority(props: {
+  task: TaskRecord;
+  onSubmit: (taskId: number, params: UpdateTaskPriorityParams) => void | Promise<void>;
 }) {
+  const priorityFieldId = useId();
+  const [workPriority, setWorkPriority] = useState<TaskWorkPriority>(props.task.workPriority);
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    void props.onSubmit(props.task.id, { work_priority: workPriority });
+  }
+
   return (
-    <select value={props.value} onChange={(event) => props.onChange(event.target.value as TaskWorkPriority)}>
-      {Task.workPriorities.map((value) => (
-        <option key={value} value={value}>
-          {value}
-        </option>
-      ))}
-    </select>
+    <form onSubmit={handleSubmit}>
+      <label htmlFor={priorityFieldId}>Work priority</label>
+
+      <select
+        id={priorityFieldId}
+        name="work_priority"
+        value={workPriority}
+        onChange={(event) => setWorkPriority(event.currentTarget.value as TaskWorkPriority)}
+      >
+        {TaskEnums.workPriorities.map((value) => (
+          <option key={value} value={value}>
+            {value}
+          </option>
+        ))}
+      </select>
+
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+## React With Inertia
+
+```tsx
+import { useId, type FormEvent } from "react";
+import { useForm } from "@inertiajs/react";
+import { TaskEnums, type TaskWorkPriority } from "@/lib/enums";
+
+type TaskRecord = {
+  id: number;
+  workPriority: TaskWorkPriority;
+};
+
+type UpdateTaskPriorityParams = {
+  work_priority: TaskWorkPriority;
+};
+
+export function EditTaskPriority(props: {
+  task: TaskRecord;
+}) {
+  const priorityFieldId = useId();
+  const form = useForm<UpdateTaskPriorityParams>({
+    work_priority: props.task.workPriority,
+  });
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    form.put(`/tasks/${props.task.id}`);
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <label htmlFor={priorityFieldId}>Work priority</label>
+
+      <select
+        id={priorityFieldId}
+        name="work_priority"
+        value={form.data.work_priority}
+        onChange={(event) => form.setData("work_priority", event.currentTarget.value as TaskWorkPriority)}
+        disabled={form.processing}
+      >
+        {TaskEnums.workPriorities.map((value) => (
+          <option key={value} value={value}>
+            {value}
+          </option>
+        ))}
+      </select>
+
+      <button type="submit" disabled={form.processing}>
+        Save
+      </button>
+    </form>
   );
 }
 ```
@@ -136,26 +236,87 @@ export function PrioritySelect(props: {
 
 ```vue
 <script setup lang="ts">
-import { Task, type TaskWorkPriority } from "@/lib/enums";
+import { ref, useId } from "vue";
+import { TaskEnums, type TaskWorkPriority } from "@/lib/enums";
+
+const props = defineProps<{
+  task: {
+    id: number;
+    workPriority: TaskWorkPriority;
+  };
+}>();
+
+const emit = defineEmits<{
+  submit: [taskId: number, params: { work_priority: TaskWorkPriority }];
+}>();
+
+const priorityFieldId = useId();
+const workPriority = ref<TaskWorkPriority>(props.task.workPriority);
+</script>
+
+<template>
+  <form @submit.prevent="emit('submit', props.task.id, { work_priority: workPriority })">
+    <label :for="priorityFieldId">Work priority</label>
 
-const model = defineModel<TaskWorkPriority>();
+    <select :id="priorityFieldId" v-model="workPriority" name="work_priority">
+      <option v-for="value in TaskEnums.workPriorities" :key="value" :value="value">
+        {{ value }}
+      </option>
+    </select>
+
+    <button type="submit">Save</button>
+  </form>
+</template>
+```
+
+## Vue With Inertia
+
+```vue
+<script setup lang="ts">
+import { useId } from "vue";
+import { useForm } from "@inertiajs/vue3";
+import { TaskEnums, type TaskWorkPriority } from "@/lib/enums";
+
+const props = defineProps<{
+  task: {
+    id: number;
+    workPriority: TaskWorkPriority;
+  };
+}>();
+
+const priorityFieldId = useId();
+const form = useForm<{
+  work_priority: TaskWorkPriority;
+}>({
+  work_priority: props.task.workPriority,
+});
 </script>
 
 <template>
-  <select v-model="model">
-    <option v-for="value in Task.workPriorities" :key="value" :value="value">
-      {{ value }}
-    </option>
-  </select>
+  <form @submit.prevent="form.put(`/tasks/${props.task.id}`)">
+    <label :for="priorityFieldId">Work priority</label>
+
+    <select :id="priorityFieldId" v-model="form.work_priority" name="work_priority" :disabled="form.processing">
+      <option v-for="value in TaskEnums.workPriorities" :key="value" :value="value">
+        {{ value }}
+      </option>
+    </select>
+
+    <button type="submit" :disabled="form.processing">
+      Save
+    </button>
+  </form>
 </template>
 ```
 
+The route strings are intentionally plain for the examples. In Rails apps that use `js-routes`, prefer generated route helpers instead of building URLs by hand.
+
 ## Svelte Or Plain TypeScript
 
 ```ts
-import { Task, type TaskWorkPriority } from "@/lib/enums";
+import { TaskEnums, type TaskWorkPriority } from "@/lib/enums";
 
-export const priorityOptions = Task.workPriorities.map((value: TaskWorkPriority) => ({
+export const priorityOptions = TaskEnums.workPriorities.map((value: TaskWorkPriority) => ({
   value,
   label: value,
 }));
@@ -164,9 +325,9 @@ export const priorityOptions = Task.workPriorities.map((value: TaskWorkPriority)
 ## Plain JavaScript
 
 ```js
-import { Task } from "@/lib/enums";
+import { TaskEnums } from "@/lib/enums";
 
-export const priorityOptions = Task.workPriorities.map((value) => ({
+export const priorityOptions = TaskEnums.workPriorities.map((value) => ({
   value,
   label: value,
 }));
@@ -177,9 +338,9 @@ export const priorityOptions = Task.workPriorities.map((value) => ({
 The generated values are intentionally raw enum values. Use your frontend i18n layer to label them:
 
 ```ts
-import { Task } from "@/lib/enums";
+import { TaskEnums } from "@/lib/enums";
 
-Task.workPriorities.map((value) => ({
+TaskEnums.workPriorities.map((value) => ({
   value,
   label: t(`enums.task.workPriorities.${value}`),
 }));
@@ -208,13 +369,19 @@ The installer creates `config/initializers/typed_enums.rb`:
 # frozen_string_literal: true
 
 TypedEnums.configure do |config|
+  # Generated JavaScript and TypeScript declaration files are written here.
   config.output_dir = "app/javascript/lib"
-  config.root_model_class = "ApplicationRecord"
+
+  # Automatically regenerate enum files in development.
   config.auto_generate_in_development = true
+
+  # Watch app/models in development and regenerate after saves.
   config.watch_models_in_development = true
 end
 ```
 
+If your enum models do not inherit from `ApplicationRecord`, configure `config.root_model_class` to the shared base class that exposes your Active Record descendants.
+
 Keep the output directory isolated and import generated code from that directory. The generator never appends to user-owned frontend files.
 
 ## Rake Tasks
@@ -287,7 +454,7 @@ app/javascript/lib/enums.d.ts
 ```
 
 ```ts
-export const AdminTask = {};
+export const AdminTaskEnums = {};
 ```
 
 ## Empty Output
@@ -310,7 +477,7 @@ Enum values are written to frontend-visible JavaScript files. Do not put secrets
 
 ## Compatibility
 
-The gem targets modern Rails applications and supports Rails 7.1 or newer. It uses Active Record enum APIs and ActiveSupport inflections, and it does not depend on any frontend framework.
+The gem targets modern Rails applications and supports Rails 7.1 or newer. It uses Active Record enum APIs and ActiveSupport inflections, and it does not depend on any frontend framework. The React, Vue, and Inertia examples target current framework versions and are provided as copyable usage examples for generated enum values.
 
 ## Contributing
 

data/lib/typed_enums/model_scanner.rb

@@ -42,6 +42,7 @@ module TypedEnums
 
     def build_definition(model:, attribute_name:, values:)
       model_export_name = name_builder.model_export_name(model.name)
+      model_type_name = name_builder.model_type_name(model.name)
       rails_mapping_name = name_builder.rails_mapping_name(attribute_name)
 
       EnumDefinition.new(
@@ -50,7 +51,7 @@ module TypedEnums
         attribute_name:,
         rails_mapping_name:,
         typescript_property_name: name_builder.property_name(rails_mapping_name),
-        typescript_type_name: name_builder.type_name(model_export_name:, rails_mapping_name:),
+        typescript_type_name: name_builder.type_name(model_export_name: model_type_name, rails_mapping_name:),
         values: values.keys.map(&:to_s)
       )
     end

data/lib/typed_enums/naming/name_builder.rb

@@ -6,6 +6,10 @@ module TypedEnums
   module Naming
     class NameBuilder
       def model_export_name(model_name)
+        "#{model_type_name(model_name)}Enums"
+      end
+
+      def model_type_name(model_name)
         model_name.to_s.split("::").map(&:camelize).join
       end
 

data/lib/typed_enums/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedEnums
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_enums
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ackermann