Feat/tunning links

.changeset/rude-pillows-train.md

@@ -0,0 +1,5 @@
+---
+'vite-plugin-kit-routes': patch
+---
+
+rename object_keys_format to format

.changeset/unlucky-bulldogs-occur.md

@@ -0,0 +1,5 @@
+---
+'vite-plugin-kit-routes': patch
+---
+
+remove exdend in the config to reduce the file nesting

.gitignore

@@ -6,5 +6,6 @@ coverage/
 .idea/
 .svelte-kit/
 .env
+.DS_Store
 
-stats.html
+stats.html

packages/vite-plugin-kit-routes/src/lib/ROUTES.ts

@@ -136,10 +136,8 @@ const appendSp = (sp?: Record<string, string | number | undefined>) => {
  * import { kitRoutes } from 'vite-plugin-kit-routes'
  *
  * kitRoutes<KIT_ROUTES>({
- *  extend: {
- *    PAGES: {
- *      // here, "paths" it will be typed!
- *    }
+ *  PAGES: {
+ *    // here, "paths" it will be typed!
  *  }
  * })
  * ```

packages/vite-plugin-kit-routes/src/lib/fs.ts

@@ -2,7 +2,10 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
 export function read(pathFile: string) {
-  return readFileSync(pathFile, { encoding: 'utf8' })
+  try {
+    return readFileSync(pathFile, { encoding: 'utf8' })
+  } catch (error) {}
+  return null
 }
 
 export function write(pathFile: string, data: string[]) {

packages/vite-plugin-kit-routes/src/lib/plugin.ts

@@ -10,21 +10,16 @@ import { read, write } from './fs.js'
 
 const { visit } = recast.types
 
-export type Options<
-  T extends {
-    PAGES: Record<string, string>
-    SERVERS: Record<string, string>
-    ACTIONS: Record<string, string>
-    Params: Record<string, string>
-  } = {
-    PAGES: Record<string, string>
-    SERVERS: Record<string, string>
-    ACTIONS: Record<string, string>
-    Params: Record<string, string>
-  },
-> = {
+type ExtendTypes = {
+  PAGES: Record<string, string>
+  SERVERS: Record<string, string>
+  ACTIONS: Record<string, string>
+  Params: Record<string, string>
+}
+
+export type Options<T extends ExtendTypes = ExtendTypes> = {
   /**
-   * run command after file updated
+   * run any command after an update of some routes.
    *
    * @example
    * ```ts
@@ -47,7 +42,7 @@ export type Options<
    * PAGES.site_id_two_hello
    * ```
    */
-  object_keys_format?: '/' | '_'
+  format?: '/' | '_'
 
   /**
    * default is: `string | number`
@@ -59,16 +54,39 @@ export type Options<
    *
    * when `with`, each paths get an extra arg for open search param
    *
+   * ⚠️ **We don't recommend to use it, but it can be useful in some cases.**
+   *
    * Can be tuned at individual path level
    */
   extra_search_params?: 'with' | 'without'
 
-  extend?: {
-    PAGES?: Partial<{ [K in keyof T['PAGES']]: CustomPath<Extract<T['PAGES'][K], string>> }>
-    SERVERS?: Partial<{ [K in keyof T['SERVERS']]: CustomPath<Extract<T['SERVERS'][K], string>> }>
-    ACTIONS?: Partial<{ [K in keyof T['ACTIONS']]: CustomPath<Extract<T['ACTIONS'][K], string>> }>
-    LINKS?: Record<string, { href: string } & CustomPath<string>>
-  }
+  PAGES?: Partial<{ [K in keyof T['PAGES']]: CustomPath<Extract<T['PAGES'][K], string>> }>
+  SERVERS?: Partial<{ [K in keyof T['SERVERS']]: CustomPath<Extract<T['SERVERS'][K], string>> }>
+  ACTIONS?: Partial<{ [K in keyof T['ACTIONS']]: CustomPath<Extract<T['ACTIONS'][K], string>> }>
+  /**
+   * ```ts
+   * {
+   *   // ... Example ...
+   *   LINKS: {
+   *    // reference to a hardcoded link
+   *    twitter: 'https://twitter.com/jycouet',
+   *    // ✅ <a href={LINKS.twitter}>Twitter</a>
+   *
+   *    // reference to link with params! (Like svelteKit routes add [ ] to specify params)
+   *    mailto: 'mailto:[email]',
+   *    // ✅ <a href={LINKS.mailto({ email: 'me@super.dev' })}>Mail</a>
+   *
+   *    // reference to link with params & search params!
+   *    twitter_post: {
+   *      href: 'https://twitter.com/[name]/status/[id]',
+   *      explicit_search_params: { limit: { type: 'number' } }
+   *    }
+   *    // ✅ <a href={LINKS.twitter_post({ name: 'jycouet', id: '1727089217707159569', limit: 12 })}>Twitter Post</a>
+   *  }
+   * }
+   * ```
+   */
+  LINKS?: Record<string, string | ({ href: string } & CustomPath<string>)>
 
   /**
    * To override the type of a param globally.
@@ -87,8 +105,34 @@ export type Options<
 }
 
 export type CustomPath<Params extends string | never = string> = {
+  /**
+   * Add to this route an explicit search params (with some options)
+   * @example
+   * explicit_search_params {
+   *   limit: {                   // name of the search param
+   *     required?: true | false, // default: false
+   *     type: 'number',          // default: 'string | number'
+   *     default: '12',           // default: undefined
+   *   }
+   * }
+   */
   explicit_search_params?: Record<string, ExplicitSearchParam>
+  /**
+   * Specify for this route the type & a default.
+   * @example
+   * params {
+   *   id: {                   // name of the param (if you set the plugin `kitRoutes<KIT_ROUTES>`, it will be typed!)
+   *     type: 'number',       // default: 'string | number'
+   *     default: '12',        // default: undefined
+   *   }
+   * }
+   */
   params?: Partial<Record<Params, ExtendParam>>
+  /**
+   * If `with`, you can add extra search params to this route (without any typecheck!)
+   *
+   * ⚠️ **We don't recommend to use it, but it can be useful in some cases.**
+   */
   extra_search_params?: 'default' | 'with' | 'without'
 }
 
@@ -126,7 +170,7 @@ export function rmvGroups(key: string) {
 export function formatKey(key: string, options?: Options) {
   let toRet = rmvGroups(key)
 
-  if (options?.object_keys_format === undefined || options?.object_keys_format === '/') {
+  if (options?.format === undefined || options?.format === '/') {
     return toRet
   }
 
@@ -167,8 +211,10 @@ const getFileKeys = (
   const useWithAppendSp = withAppendSp && options?.extra_search_params === 'with'
 
   if (type === 'LINKS') {
-    const toRet = Object.entries(options?.extend?.LINKS ?? {}).map(c => {
-      return fileToMetadata(c[0], c[1].href, type, options, useWithAppendSp)
+    const toRet = Object.entries(options?.LINKS ?? {}).map(c => {
+      const hrefToUse = typeof c[1] === 'string' ? c[1] : c[1].href
+
+      return fileToMetadata(c[0], hrefToUse, type, options, useWithAppendSp)
     })
     return toRet.filter(c => c !== null) as {
       keyToUse: string
@@ -210,7 +256,7 @@ export const fileToMetadata = (
   let toRet = rmvGroups(originalValue)
 
   // custom conf
-  const viteCustomPathConfig = options?.extend?.[type]
+  const viteCustomPathConfig = options?.[type]
   let customConf: CustomPath = {
     extra_search_params: 'default',
   }
@@ -466,7 +512,7 @@ const getActionsOfServerPages = (pathFile: string) => {
   return { actions, withLoad }
 }
 
-const run = (options?: Options) => {
+export const run = (options?: Options) => {
   const objTypes = [
     { type: 'PAGES', files: getFileKeys('PAGES', options, true) },
     { type: 'SERVERS', files: getFileKeys('SERVERS', options, true) },
@@ -479,7 +525,7 @@ const run = (options?: Options) => {
   objTypes
     .filter(c => c.type !== 'LINKS')
     .forEach(o => {
-      Object.entries(options?.extend?.[o.type] ?? {}).forEach(e => {
+      Object.entries(options?.[o.type] ?? {}).forEach(e => {
         const [key, cPath] = e
         const found = o.files.find(c => c.keyToUse === key)
         if (!found) {
@@ -544,10 +590,8 @@ const appendSp = (sp?: Record<string, string | number | undefined>) => {
 * import { kitRoutes } from 'vite-plugin-kit-routes'
 * 
 * kitRoutes<KIT_ROUTES>({
-*  extend: {
-*    PAGES: {
-*      // here, "paths" it will be typed!
-*    }
+*  PAGES: {
+*    // here, "paths" it will be typed!
 *  }
 * })
 * \`\`\`
@@ -700,19 +744,7 @@ ${objTypes
  * })
  * ```
  */
-export function kitRoutes<
-  T extends {
-    PAGES: Record<string, string>
-    SERVERS: Record<string, string>
-    ACTIONS: Record<string, string>
-    Params: Record<string, string>
-  } = {
-    PAGES: Record<string, string>
-    SERVERS: Record<string, string>
-    ACTIONS: Record<string, string>
-    Params: Record<string, string>
-  },
->(options?: Options<T>): Plugin[] {
+export function kitRoutes<T extends ExtendTypes = ExtendTypes>(options?: Options<T>): Plugin[] {
   return [
     // Run the thing at startup
     {