feat(form): rename $save to $submit

Akryum · Akryum · commit dbf46cb516f1 · 2025-04-06T17:11:15.000+02:00
diff --git a/docs/guide/data/form.md b/docs/guide/data/form.md
@@ -19,7 +19,7 @@ The form object is a reactive object that contains the data of the form. You can
 It has several special properties:
 
 - `$reset()`: a method that resets the form to its initial state.
-- `$save()`: a method that saves the form and creates a new item.
+- `$submit()`: a method that saves the form and creates a new item.
 - `$loading`: a boolean that indicates whether the form is being saved.
 - `$error`: an error object that contains the error if the form could not be saved.
 - `$schema` the validation schema for the form object (see [schema validation](#schema-validation)).
@@ -39,7 +39,7 @@ createTodo.$onSaved(() => {
 </script>
 
 <template>
-  <form @submit.prevent="createTodo.$save()">
+  <form @submit.prevent="createTodo.$submit()">
     <!-- Input -->
     <input ref="input" v-model="createTodo.title">
     <!-- Submit -->
@@ -81,7 +81,7 @@ The update for object has the following special properties:
 
 - `$reset()`: a method that resets the form to its initial state.
 
-- `$save()`: a method that saves the form and updates the item.
+- `$submit()`: a method that saves the form and updates the item.
 
 - `$loading`: a boolean that indicates whether the form is being saved.
 
@@ -116,7 +116,7 @@ updateTodo.$onSaved(() => emit('close'))
 </script>
 
 <template>
-  <form @submit.prevent="updateTodo.$save()">
+  <form @submit.prevent="updateTodo.$submit()">
     <!-- Input -->
     <input v-model="updateTodo.title">
     <!-- Submit -->
@@ -173,7 +173,7 @@ const createTodo = store.todos.createForm()
   <UForm
     :state="createTodo"
     :schema="createTodo.$schema"
-    @submit="createTodo.$save()"
+    @submit="createTodo.$submit()"
   >
     <!-- UFormFields here -->
   </UForm>
diff --git a/docs/guide/model/model.md b/docs/guide/model/model.md
@@ -245,7 +245,7 @@ const createTodo = store.todos.createForm()
   <UForm
     :state="createTodo"
     :schema="createTodo.$schema"
-    @submit="createTodo.$save()"
+    @submit="createTodo.$submit()"
   >
     <!-- UFormFields here -->
   </UForm>
diff --git a/packages/playground-drizzle-2/app/components/todo/TodoEditForm.vue b/packages/playground-drizzle-2/app/components/todo/TodoEditForm.vue
@@ -18,7 +18,7 @@ updateTodo.$onSaved(() => emit('close'))
     :state="updateTodo"
     :schema="updateTodo.$schema"
     class="flex flex-col gap-4"
-    @submit="updateTodo.$save()"
+    @submit="updateTodo.$submit()"
   >
     <UFormField
       label="Text"
diff --git a/packages/playground-drizzle-2/app/pages/todo.vue b/packages/playground-drizzle-2/app/pages/todo.vue
@@ -17,7 +17,7 @@ createTodo.$onSaved(() => {
       :state="createTodo"
       :schema="createTodo.$schema"
       class="mb-4"
-      @submit="createTodo.$save()"
+      @submit="createTodo.$submit()"
     >
       <UButtonGroup
         class="w-full"
@@ -29,7 +29,7 @@ createTodo.$onSaved(() => {
           autofocus
           size="xl"
           class="w-full"
-          @keydown.enter.prevent="createTodo.$save()"
+          @keydown.enter.prevent="createTodo.$submit()"
         />
 
         <UButton
diff --git a/packages/playground-drizzle/app/app.vue b/packages/playground-drizzle/app/app.vue
@@ -25,7 +25,7 @@ createTodo.$onSaved(() => {
         :state="createTodo"
         :schema="createTodo.$schema"
         class="flex-1 min-w-0"
-        @submit="createTodo.$save()"
+        @submit="createTodo.$submit()"
       >
         <UButtonGroup
           class="w-full"
@@ -37,7 +37,7 @@ createTodo.$onSaved(() => {
             autofocus
             size="xl"
             class="w-full"
-            @keydown.enter.prevent="createTodo.$save()"
+            @keydown.enter.prevent="createTodo.$submit()"
           />
 
           <UButton
diff --git a/packages/playground-drizzle/app/components/todo/TodoEditForm.vue b/packages/playground-drizzle/app/components/todo/TodoEditForm.vue
@@ -18,7 +18,7 @@ updateTodo.$onSaved(() => emit('close'))
     :state="updateTodo"
     :schema="updateTodo.$schema"
     class="flex flex-col gap-4"
-    @submit="updateTodo.$save()"
+    @submit="updateTodo.$submit()"
   >
     <UFormField
       label="Text"
diff --git a/packages/playground-nuxt-directus/app/app.vue b/packages/playground-nuxt-directus/app/app.vue
@@ -31,7 +31,7 @@ createTodo.$onSaved(() => {
         :state="createTodo"
         :schema="createTodo.$schema"
         class="flex-1 min-w-0"
-        @submit="createTodo.$save()"
+        @submit="createTodo.$submit()"
       >
         <UButtonGroup
           class="w-full"
@@ -43,7 +43,7 @@ createTodo.$onSaved(() => {
             autofocus
             size="xl"
             class="w-full"
-            @keydown.enter.prevent="createTodo.$save()"
+            @keydown.enter.prevent="createTodo.$submit()"
           />
 
           <UButton
diff --git a/packages/playground-nuxt-directus/app/components/todo/TodoEditForm.vue b/packages/playground-nuxt-directus/app/components/todo/TodoEditForm.vue
@@ -18,7 +18,7 @@ updateTodo.$onSaved(() => emit('close'))
     :state="updateTodo"
     :schema="updateTodo.$schema"
     class="flex flex-col gap-4"
-    @submit="updateTodo.$save()"
+    @submit="updateTodo.$submit()"
   >
     <UFormField
       label="Text"
diff --git a/packages/playground/app/components/todo/TodoEditForm.vue b/packages/playground/app/components/todo/TodoEditForm.vue
@@ -18,7 +18,7 @@ updateTodo.$onSaved(() => emit('close'))
     :state="updateTodo"
     :schema="updateTodo.$schema"
     class="flex flex-col gap-4"
-    @submit="updateTodo.$save()"
+    @submit="updateTodo.$submit()"
   >
     <UFormField
       label="Text"
diff --git a/packages/playground/app/pages/chat.vue b/packages/playground/app/pages/chat.vue
@@ -27,7 +27,7 @@ createChatMessage.$onSaved(() => {
       placeholder="Type your message here..."
       icon="lucide:message-circle"
       autofocus
-      @keyup.enter="createChatMessage.$save()"
+      @keyup.enter="createChatMessage.$submit()"
     />
 
     <div class="flex-1 min-h-0 overflow-y-auto flex flex-col gap-2">
diff --git a/packages/playground/app/pages/todo/index.vue b/packages/playground/app/pages/todo/index.vue
@@ -17,7 +17,7 @@ createTodo.$onSaved(() => {
       :state="createTodo"
       :schema="createTodo.$schema"
       class="mb-4"
-      @submit="createTodo.$save()"
+      @submit="createTodo.$submit()"
     >
       <UButtonGroup
         class="w-full"
@@ -29,7 +29,7 @@ createTodo.$onSaved(() => {
           autofocus
           size="xl"
           class="w-full"
-          @keydown.enter.prevent="createTodo.$save()"
+          @keydown.enter.prevent="createTodo.$submit()"
         />
 
         <UButton
diff --git a/packages/shared/src/types/form.ts b/packages/shared/src/types/form.ts
@@ -0,0 +1,16 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+export interface FormObjectBase<
+  TResult,
+  TSchema extends StandardSchemaV1,
+> {
+  /**
+   * @deprecated Use `$submit` instead
+   */
+  $save: () => Promise<TResult>
+  $submit: () => Promise<TResult>
+  $reset: () => void
+  $schema: TSchema
+  $error: Error | null
+  $loading: boolean
+}
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
@@ -1,4 +1,5 @@
 export * from './cache.js'
+export * from './form.js'
 export * from './hooks.js'
 export * from './item.js'
 export * from './model.js'
diff --git a/packages/shared/src/types/mutation.ts b/packages/shared/src/types/mutation.ts
@@ -1,4 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { FormObjectBase } from './form'
 import type { Model, ModelDefaults, ModelList, ResolvedModel, ResolvedModelItem } from './model'
 
 export interface MutationOperation<
@@ -20,17 +21,11 @@ export interface MutationSpecialProps {
   // To be extended
 }
 
-export interface CreateFormObjectBase<
+export type CreateFormObjectBase<
   TModel extends Model,
   TModelDefaults extends ModelDefaults,
   TModelList extends ModelList,
-> {
-  $save: () => Promise<ResolvedModelItem<TModel, TModelDefaults, TModelList>>
-  $reset: () => void
-  $schema: NonNullable<NonNullable<TModel['formSchema']>['create']>
-  $error: Error | null
-  $loading: boolean
-}
+> = FormObjectBase<ResolvedModelItem<TModel, TModelDefaults, TModelList>, NonNullable<NonNullable<TModel['formSchema']>['create']>>
 
 export type CreateFormObject<
   TModel extends Model,
@@ -40,17 +35,11 @@ export type CreateFormObject<
   & CreateFormObjectBase<TModel, TModelDefaults, TModelList>
   & Partial<ResolvedModelItem<TModel, TModelDefaults, TModelList>>
 
-export interface UpdateFormObjectBase<
+export type UpdateFormObjectBase<
   TModel extends Model,
   TModelDefaults extends ModelDefaults,
   TModelList extends ModelList,
-> {
-  $save: () => Promise<ResolvedModelItem<TModel, TModelDefaults, TModelList>>
-  $reset: () => Promise<void>
-  $schema: NonNullable<NonNullable<TModel['formSchema']>['update']>
-  $error: Error | null
-  $loading: boolean
-}
+> = FormObjectBase<ResolvedModelItem<TModel, TModelDefaults, TModelList>, NonNullable<NonNullable<TModel['formSchema']>['update']>>
 
 export type UpdateFormObject<
   TModel extends Model,
diff --git a/packages/vue/src/api.ts b/packages/vue/src/api.ts
@@ -1,4 +1,4 @@
-import type { CreateFormObject, CreateFormObjectBase, CustomHookMeta, Exactly, FindFirstOptions, FindManyOptions, FindOptions, HybridPromise, Model, ModelDefaults, ModelList, ResolvedModel, ResolvedModelItem, ResolvedModelItemBase, StandardSchemaV1, UpdateFormObject, WrappedItem } from '@rstore/shared'
+import type { CreateFormObject, CreateFormObjectBase, CustomHookMeta, Exactly, FindFirstOptions, FindManyOptions, FindOptions, HybridPromise, Model, ModelDefaults, ModelList, ResolvedModel, ResolvedModelItem, ResolvedModelItemBase, StandardSchemaV1, UpdateFormObject, UpdateFormObjectBase, WrappedItem } from '@rstore/shared'
 import type { EventHookOn } from '@vueuse/core'
 import type { MaybeRefOrGetter } from 'vue'
 import type { VueLiveQueryReturn } from './live'
@@ -253,7 +253,7 @@ export function createModelApi<
             Object.assign(form, formOptions.defaultValues())
           }
         },
-        async $save() {
+        async $submit() {
           form.$loading = true
           form.$error = null
           try {
@@ -277,6 +277,10 @@ export function createModelApi<
             form.$loading = false
           }
         },
+        $save() {
+          console.warn(`$save() is deprecated, use $submit() instead`)
+          return this.$submit()
+        },
         $schema: markRaw(formOptions?.schema ?? model.formSchema.create),
         $onSaved: onSaved.on,
       } satisfies CreateFormObjectBase<TModel, TModelDefaults, TModelList> & CreateFormObjectAdditional<TModel, TModelDefaults, TModelList>) as TReturn
@@ -309,7 +313,7 @@ export function createModelApi<
 
       const form = reactive({
         ...formOptions?.defaultValues?.(),
-        ...initialData,
+        ...initialData as object,
 
         $error: null,
         $loading: false,
@@ -327,7 +331,7 @@ export function createModelApi<
           }
           form.$changedProps = {}
         },
-        async $save() {
+        async $submit() {
           form.$loading = true
           form.$error = null
           try {
@@ -356,9 +360,13 @@ export function createModelApi<
             form.$loading = false
           }
         },
+        $save() {
+          console.warn(`$save() is deprecated, use $submit() instead`)
+          return this.$submit()
+        },
         $schema: markRaw(formOptions?.schema ?? model.formSchema.update),
         $onSaved: onSaved.on,
-      } satisfies TReturn) as TReturn
+      } satisfies UpdateFormObjectBase<TModel, TModelDefaults, TModelList> & UpdateFormObjectAdditional<TModel, TModelDefaults, TModelList>) as TReturn
 
       // Detect changed props
       const proxy = new Proxy(form, {

Original file line number	Diff line number	Diff line change
`@@ -245,7 +245,7 @@ const createTodo = store.todos.createForm()`
`245`	`245`	`<UForm`
`246`	`246`	`:state="createTodo"`
`247`	`247`	`:schema="createTodo.$schema"`
`248`		`- @submit="createTodo.$save()"`
	`248`	`+ @submit="createTodo.$submit()"`
`249`	`249`	`>`
`250`	`250`	`<!-- UFormFields here -->`
`251`	`251`	`</UForm>`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ updateTodo.$onSaved(() => emit('close'))`
`18`	`18`	`:state="updateTodo"`
`19`	`19`	`:schema="updateTodo.$schema"`
`20`	`20`	`class="flex flex-col gap-4"`
`21`		`- @submit="updateTodo.$save()"`
	`21`	`+ @submit="updateTodo.$submit()"`
`22`	`22`	`>`
`23`	`23`	`<UFormField`
`24`	`24`	`label="Text"`