Cleanup

Author: ciscoheat

1.0 RC release.md

@@ -2,25 +2,36 @@
 
 After plenty of work, the first release candidate for **Superforms 1.0** is ready!
 
-First a feature list, so you'll see what's new, then a comprehensive migration guide.
+Here's a feature list, so you'll see what's new, after that a comprehensive migration guide.
 
 ## New and updated features
 
 ### Automatic form id
 
-Setting a form `id` for multiple forms is not required anymore when using `use:enhance`, unless the forms are using the same schema.
+Setting a form `id` for multiple forms on the same page is not required anymore when using `use:enhance`.
 
 ```diff
 const loginForm = await superValidate(loginSchema, {
--    id: 'loginForm'
+-  id: 'loginForm'
 });
 
 const registerForm = await superValidate(registerSchema, {
--    id: 'registerForm'
+-  id: 'registerForm'
 });
+
+return { loginForm, registerForm }
+```
+
+With one exception, if the forms are using the same schema:
+
+```ts
+const form1 = await superValidate(schema, { id: 'form1' });
+const form2 = await superValidate(schema, { id: 'form2' });
+
+return { form1, form2 };
 ```
 
-Without `use:enhance`, an id can be specified in the options or in a hidden form field called `__superform_id`.
+If you're having multiple forms without `use:enhance`, an id can be specified in the options, or in a hidden form field called `__superform_id`.
 
 For extra safety, a warning will be emitted if identical id's are detected.
 
@@ -39,7 +50,7 @@ This was previously an undocumented function called `defaultData`. If you've use
 
 ### superValidateSync
 
-When using `superValidate` on the client, you previously had to use a `+page.ts` file to call `superValidate`, since it is asynchronous. But now you can import `superValidateSync` and use it in components directly. Can be very convenient in SPA:s.
+When using `superValidate` on the client, you previously had to use a `+page.ts` file to call `superValidate`, since it is asynchronous. But now you can import `superValidateSync` and use it in components directly (which assumes that there is no async validation in the schema). Can be very convenient in SPA:s.
 
 ```svelte
 <script lang="ts">
@@ -53,7 +64,7 @@ When using `superValidate` on the client, you previously had to use a `+page.ts`
 
 ### String path accessors
 
-When you wanted to set errors, use proxies and nested data in components, the array syntax was a bit clunky. It has now been replaced with a typesafe string path, so you can write it just as you would access an object property:
+When you wanted to set errors, use proxies and have nested data in components, the array syntax was a bit clunky. It has now been replaced with a typesafe string path, so you can write it just as you would access an object property:
 
 ```diff
 import { setError } from 'sveltekit-superforms/server'
@@ -91,7 +102,9 @@ const schema = z
   .refine((data) => password == confirmPassword, `Passwords doesn't match.`);
 ```
 
-The above will be available on the client as `$errors._errors` as before, and will be removed (or added) upon client-side validation.
+The above error set in `refine` will be available on the client as `$errors._errors` as before, and will be removed (or added) during client-side validation.
+
+If you'd like the error to persist, `message` will persist until the next form submission.
 
 ```ts
 const form = await superValidate(request, schema);
@@ -102,35 +115,70 @@ if (form.data.password != form.data.confirmPassword)
   return message(form, `Passwords doesn't match`, { status: 400 });
 ```
 
-Unlike form-level messages, `message` will persist until the next form submission.
-
-## validate, setError, proxy methods (ending with `Proxy`)
+## setError (again), validate, proxy methods (ending with `Proxy`)
 
 `FieldPath` is gone - the above methods are now using a string accessor like `tags[2].id` instead of an array like `['tags', 2, 'id']`.
 
 ```diff
-- setError(form, ['tags', i, 'name'], 'Incorrect name');
-+ setError(form, `tags[${i}].name`, 'Incorrect name');
+const { form, enhance, validate } = superForm(data.form)
+
+- validate(['tags', i, 'name'], { update: false });
++ validate(`tags[${i}].name`, { update: false });
 ```
 
-This also applies to generic components, so you should change the type of the field prop, as described on the componentization page:
+This also applies to generic components, so you should change the type of the field prop, as described on the [componentization page](https://superforms.vercel.app/components):
 
 ```svelte
 <script lang="ts">
   import type { z, AnyZodObject } from 'zod';
-  import type { UnwrapEffects } from 'sveltekit-superforms';
-  import type { SuperForm, StringPath } from 'sveltekit-superforms/client';
-  import { formFieldProxy } from 'sveltekit-superforms/client';
+  import type { ZodValidation, StringPathLeaves } from '$lib';
+  import { formFieldProxy, type SuperForm } from '$lib/client';
 
   type T = $$Generic<AnyZodObject>;
 
-  export let form: SuperForm<UnwrapEffects<T>, unknown>;
-  export let field: string & StringPath<z.infer<UnwrapEffects<T>>>;
+  export let form: SuperForm<ZodValidation<T>, unknown>;
+  export let field: string & StringPathLeaves<z.infer<T>>;
 
   const { path, value, errors, constraints } = formFieldProxy(form, field);
 </script>
 ```
 
+Also note that **arrays and objects cannot be used in formFieldProxy**. So if your schema is defined as:
+
+```ts
+import { formFieldProxy } from 'sveltekit-superforms/client';
+
+const schema = z.object({
+  tags: z
+    .object({
+      id: z.number(),
+      name: z.string().min(1)
+    })
+    .array()
+});
+
+const formData = superForm(data.form);
+
+// This won't work properly!
+const tags = formFieldProxy(formData, 'tags');
+
+// Not this either
+const tag = formFieldProxy(formData, 'tags[0]');
+
+// But this will work
+const tagName = formFieldProxy(formData, 'tags[0].name');
+```
+
+This only applies to `formFieldProxy` because it maps to errors and constraints as well as the form. If you want to proxy a form value only, the `fieldProxy` will work with any of the above.
+
+```ts
+import { fieldProxy } from 'sveltekit-superforms/client';
+
+const { form } = superForm(data.form);
+
+const tags = fieldProxy(form, 'tags');
+```
+
 ## allErrors, firstError
 
 The signature for `allErrors` and `firstError` has changed, to make it easier to group related messages:
@@ -140,21 +188,38 @@ The signature for `allErrors` and `firstError` has changed, to make it easier to
 + { path: string; messages: string[] }
 ```
 
-The path follows the same format as the string accessor path above.
+The path follows the same format as the above described string accessor path. If you want to display all messages grouped:
 
 ```svelte
 {#if $allErrors.length}
   <ul>
     {#each $allErrors as error}
       <li>
         <b>{error.path}:</b>
-        {error.messages}
+        {error.messages.join('. ')}.
       </li>
     {/each}
   </ul>
 {/if}
 ```
 
+Or as before, separate for each error:
+
+```svelte
+{#if $allErrors.length}
+  <ul>
+    {#each $allErrors as error}
+      {#each error.messages as message}
+        <li>
+          <b>{error.path}:</b>
+          {message}.
+        </li>
+      {/each}
+    {/each}
+  </ul>
+{/if}
+```
+
 ## defaultData
 
 The `defaultData` function is now called `defaultValues`.
@@ -204,4 +269,13 @@ The following `superValidate` options have changed:
 const form = await superValidate(schema, { errors: true });
 ```
 
-The [changelog](https://github.com/ciscoheat/sveltekit-superforms/blob/main/CHANGELOG.md) has a full list of changes that aren't breaking. So please try this release candidate, and let me know in a [Github issue](https://github.com/ciscoheat/sveltekit-superforms/issues) or on [Discord](https://discord.gg/AptebvVuhB) if you find some problem. Thank you for helping out towards 1.0!
+# Try it out!
+
+To install this RC, update `package.json` with the new version, then update:
+
+```diff
+-  "sveltekit-superforms": "^0.8.7",
++  "sveltekit-superforms": "^1.0.0-rc.1",
+```
+
+The [changelog](https://github.com/ciscoheat/sveltekit-superforms/blob/main/CHANGELOG.md) has a full list of changes. So please try this release candidate, and let me know in a [Github issue](https://github.com/ciscoheat/sveltekit-superforms/issues) or on [Discord](https://discord.gg/AptebvVuhB) if you find some problem. Thank you for helping out towards 1.0!

CHANGELOG.md

@@ -5,7 +5,7 @@ Headlines: Added, Changed, Deprecated, Removed, Fixed, Security
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.0.0-rc.1]
 
 ### Changed
 

src/index.test.ts

@@ -642,17 +642,17 @@ describe('Errors', async () => {
     );
 
     expect(findErrors(form.errors)).toStrictEqual([
-      { path: ['id'], messages: ['Required'] },
+      { path: 'id', messages: ['Required'] },
       {
-        path: ['users', '0', 'name'],
+        path: 'users[0].name',
         messages: ['String must contain at least 2 character(s)', 'Invalid']
       },
       {
-        path: ['users', '0', 'posts', '0', 'subject'],
+        path: 'users[0].posts[0].subject',
         messages: ['String must contain at least 1 character(s)']
       },
       {
-        path: ['users', '0', 'posts', '_errors'],
+        path: 'users[0].posts._errors',
         messages: ['Array must contain at least 2 element(s)']
       }
     ]);

src/lib/client/index.ts

@@ -65,12 +65,6 @@ export {
   defaultValues
 } from '../superValidate.js';
 
-export {
-  splitPath,
-  type StringPath,
-  type StringPathLeaves
-} from '../stringPath.js';
-
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type FormOptions<T extends ZodValidation<AnyZodObject>, M> = Partial<{
   id: string;
@@ -224,8 +218,8 @@ export type SuperForm<T extends ZodValidation<AnyZodObject>, M = any> = {
   timeout: Readable<boolean>;
 
   fields: FormFields<UnwrapEffects<T>>;
-  firstError: Readable<{ path: string[]; messages: string[] } | null>;
-  allErrors: Readable<{ path: string[]; messages: string[] }[]>;
+  firstError: Readable<{ path: string; messages: string[] } | null>;
+  allErrors: Readable<{ path: string; messages: string[] }[]>;
 
   options: FormOptions<T, M>;
 

src/lib/client/proxies.ts

@@ -10,6 +10,7 @@ import type { z, AnyZodObject } from 'zod';
 import {
   splitPath,
   type StringPath,
+  type StringPathLeaves,
   type StringPathType
 } from '../stringPath.js';
 import type { ZodValidation } from '../index.js';
@@ -37,7 +38,7 @@ const defaultOptions: DefaultOptions = {
 
 export function intProxy<
   T extends Record<string, unknown>,
-  Path extends string & StringPath<T>
+  Path extends (string & StringPath<T>) | (string & StringPathLeaves<T>)
 >(
   form: Writable<T>,
   path: Path,
@@ -51,7 +52,7 @@ export function intProxy<
 
 export function booleanProxy<
   T extends Record<string, unknown>,
-  Path extends string & StringPath<T>
+  Path extends (string & StringPath<T>) | (string & StringPathLeaves<T>)
 >(
   form: Writable<T>,
   path: Path,
@@ -67,7 +68,7 @@ export function booleanProxy<
 
 export function numberProxy<
   T extends Record<string, unknown>,
-  Path extends string & StringPath<T>
+  Path extends (string & StringPath<T>) | (string & StringPathLeaves<T>)
 >(
   form: Writable<T>,
   path: Path,
@@ -81,7 +82,7 @@ export function numberProxy<
 
 export function dateProxy<
   T extends Record<string, unknown>,
-  Path extends string & StringPath<T>
+  Path extends (string & StringPath<T>) | (string & StringPathLeaves<T>)
 >(
   form: Writable<T>,
   path: Path,
@@ -101,7 +102,7 @@ export function dateProxy<
 
 export function stringProxy<
   T extends Record<string, unknown>,
-  Path extends string & StringPath<T>
+  Path extends (string & StringPath<T>) | (string & StringPathLeaves<T>)
 >(
   form: Writable<T>,
   path: Path,
@@ -124,7 +125,7 @@ export function stringProxy<
 function _stringProxy<
   T extends Record<string, unknown>,
   Type extends 'number' | 'int' | 'boolean' | 'date' | 'string',
-  Path extends string & StringPath<T>
+  Path extends (string & StringPath<T>) | (string & StringPathLeaves<T>)
 >(
   form: Writable<T>,
   path: Path,
@@ -207,7 +208,8 @@ function _stringProxy<
   };
 }
 
-export type FieldProxy<
+/*
+type FieldProxy<
   T extends AnyZodObject,
   Path extends string & StringPath<z.infer<T>>
 > = {
@@ -216,10 +218,11 @@ export type FieldProxy<
   errors?: Writable<string[] | undefined>;
   constraints?: Writable<InputConstraint | undefined>;
 };
+*/
 
 export function formFieldProxy<
   T extends ZodValidation<AnyZodObject>,
-  Path extends string & StringPath<z.infer<UnwrapEffects<T>>>
+  Path extends string & StringPathLeaves<z.infer<UnwrapEffects<T>>>
 >(
   form: SuperForm<T, unknown>,
   path: Path
@@ -250,7 +253,7 @@ export function formFieldProxy<
 
 export function fieldProxy<
   T extends object,
-  Path extends string & StringPath<T>
+  Path extends (string & StringPath<T>) | (string & StringPathLeaves<T>)
 >(form: Writable<T>, path: Path): Writable<StringPathType<T, Path>> {
   const path2 = splitPath<T>(path);
 

src/lib/index.ts

@@ -34,6 +34,8 @@ export type ZodValidation<T extends AnyZodObject> =
   | ZodEffects<ZodEffects<ZodEffects<ZodEffects<T>>>>
   | ZodEffects<ZodEffects<ZodEffects<ZodEffects<ZodEffects<T>>>>>;
 
+export { type StringPath, type StringPathLeaves } from './stringPath.js';
+
 export type RawShape<T> = T extends ZodObject<infer U> ? U : never;
 
 type UnwrappedRawShape<

src/lib/stringPath.ts

@@ -9,6 +9,17 @@ export function splitPath<T extends object>(
     .filter((p) => p) as FieldPath<T>;
 }
 
+export function mergePath(path: (string | number | symbol)[]) {
+  return path.reduce((acc: string, next) => {
+    if (typeof next === 'number' || !isNaN(parseInt(String(next), 10)))
+      acc += `[${String(next)}]`;
+    else if (!acc) acc += String(next);
+    else acc += `.${String(next)}`;
+
+    return acc;
+  }, '');
+}
+
 /**
  * Lists all paths in an object as string accessors.
  */

src/lib/superValidate.ts

@@ -36,11 +36,6 @@ import {
 } from 'zod';
 
 import { splitPath, type StringPathLeaves } from './stringPath.js';
-export {
-  splitPath,
-  type StringPath,
-  type StringPathLeaves
-} from './stringPath.js';
 
 import { clone } from './utils.js';