docs: add info preComputeUrl

Author: batosai

docs/.vitepress/config.ts

@@ -14,7 +14,7 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Guide', link: '/guide/introduction' },
+      { text: 'Guide', link: '/guide/essentials/introduction' },
       {
         text: 'Other docs',
         items: [
@@ -36,15 +36,15 @@ export default defineConfig({
             items: [
               {
                 text: 'Introduction',
-                link: '/guide/introduction'
+                link: '/guide/essentials/introduction'
               },
               {
                 text: 'Installation',
-                link: '/guide/installation'
+                link: '/guide/essentials/installation'
               },
               {
                 text: 'Configuration',
-                link: '/guide/configuration'
+                link: '/guide/essentials/configuration'
               }
             ]
           },
@@ -53,19 +53,19 @@ export default defineConfig({
             items: [
               {
                 text: 'Migration Setup',
-                link: '/guide/migration-setup'
+                link: '/guide/basic_usage/migration-setup'
               },
               {
                 text: 'Model Setup',
-                link: '/guide/model-setup'
+                link: '/guide/basic_usage/model-setup'
               },
               {
                 text: 'Controller Setup',
-                link: '/guide/controller-setup'
+                link: '/guide/basic_usage/controller-setup'
               },
               {
                 text: 'View Setup',
-                link: '/guide/view-setup'
+                link: '/guide/basic_usage/view-setup'
               }
             ]
           },
@@ -85,9 +85,13 @@ export default defineConfig({
           {
             text: 'Advanced Usage',
             items: [
+              {
+                text: 'PrecompileUrl',
+                link: '/guide/advanced_usage/pre-compile-on-demand'
+              },
               {
                 text: 'Custom converter',
-                link: '/guide/custom-converter'
+                link: '/guide/advanced_usage/custom-converter'
               },
             ]
           }

docs/changelog.md

@@ -1,10 +1,15 @@
 # Changelog
 
+## 2.2.0
+
+* add config preComputeUrl
+* fix data serialize
+
 ## 2.1.0
 
 * you may set the ffmpeg and ffprobe binary paths manually
-* add the ability to disable meta
-* add the ability to disable rename
+* add config to disable meta
+* add config to disable rename
 
 ## 2.0.2
 

docs/guide/custom-converter.md docs/guide/advanced_usage/custom-converter.md

@@ -0,0 +1,64 @@
+# Pre compute on demand
+
+We recommend not enabling the preComputeUrl option when you need the URL for just one or two queries and not within the rest of your application.
+
+For those couple of queries, you can manually compute the URLs within the controller. Here's a small helper method that you can drop on the model directly.
+
+```ts
+import type { Attachment } from '@jrmc/adonis-attachment/types/attachment'
+import { attachment, Attachmentable, attachmentManager } from '@jrmc/adonis-attachment'
+
+class User extends compose(BaseModel, Attachmentable) {
+  static async preComputeUrls(models: User | User[]) {
+    if (Array.isArray(models)) {
+      await Promise.all(models.map((model) => this.preComputeUrls(model)))
+      return
+    }
+
+    // compute url for original file
+    await attachmentManager.computeUrl(models.avatar)
+
+    // compute url for thumbnail variant
+    const thumb = models.avatar.getVariant('thumbnail')
+    await attachmentManager.computeUrl(thumb)
+
+    // compute url for medium variant with expiration time option
+    const medium = models.avatar.getVariant('medium')
+    await attachmentManager.computeUrl(medium, {
+      expiresIn: '30 mins',
+    })
+  }
+
+  @attachment({
+    variants: ['thumbnail', 'medium', 'large']
+  })
+  declare avatar: Attachment
+}
+```
+
+computeUrl method create automatically creates a signed or unsigned url depending on Drive's configuration.
+
+it's possible to pass specific options to the signed url.
+options params accepts `expiresIn`, `contentType` et `contentDisposition`.
+
+[More informations](https://flydrive.dev/docs/disk_api#getsignedurl)
+
+---
+
+And now use it as follows.
+
+```ts
+const users = await User.all()
+await User.preComputeUrls(users)
+
+return users
+```
+
+Or for a single user
+
+```ts
+const user = await User.findOrFail(1)
+await User.preComputeUrls(user)
+
+return user
+```

docs/guide/advanced_usage/pre-compile-on-demand.md

@@ -51,6 +51,18 @@ class User extends BaseModel {
 }
 ```
 
+## Specifying preComputeUrl
+
+You can enabled pre compute the URLs after SELECT queries, default is false
+
+```ts
+class User extends BaseModel {
+  @attachment({ preComputeUrl: true }) // [!code highlight]
+  declare avatar: Attachment
+}
+```
+
+
 ## Specifying meta
 
 You can disabled meta generation, default is true

docs/guide/controller-setup.md docs/guide/basic_usage/controller-setup.md

@@ -30,15 +30,28 @@ await user.avatar.getSignedUrl('thumbnail')
 
 getSignedUrl options params accepts `expiresIn`, `contentType` et `contentDisposition`. [More informations](https://flydrive.dev/docs/disk_api#getsignedurl)
 
+### If preComputeUrl is enabled
 
-## By serialize
+```edge
+<img src="{{ user.avatar.url }}" loading="lazy" alt="" />
+<img src="{{ user.avatar.getVariant('thumbnail').url }}" loading="lazy" alt="" />
+```
 
-```ts
-await user.avatar.toJSON()
+
+## URLs for Inertia template
+
+::: code-group
+```js
+<img src={user.avatar.thumbnail.url} loading="lazy" alt="" />
 ```
 
 ```vue
 <img :src="user.avatar.thumbnail.url" loading="lazy" alt="" />
-<img :src="user.avatar.thumbnail.signedUrl" loading="lazy" alt="" />
 ```
 
+```svelte
+<img src={user.avatar.thumbnail.url} loading="lazy" alt="" />
+```
+:::
+
+preComputeUrl is required.

docs/guide/migration-setup.md docs/guide/basic_usage/migration-setup.md

@@ -18,7 +18,7 @@ export default defineConfig({
 })
 ```
 
-### converters
+## converters
 
 |OPTIONS:  | DESCRIPTIONS:            |
 | -------- | ------------------------ |
@@ -28,13 +28,26 @@ export default defineConfig({
 
 ---
 
-### meta (optional, default true)
+## preComputeUrl (optional, default false)
+
+enable the preComputeUrl flag to pre compute the URLs after SELECT queries.
+
+```typescript
+export default defineConfig({
+  preComputeUrl: true, // [!code focus]
+  converters: [
+    // ...
+  ]
+})
+```
+
+## meta (optional, default true)
 
 you can set the default meta generation or not
 
 ```typescript
 export default defineConfig({
-  meta: false, // [!code focus],
+  meta: false, // [!code focus]
   converters: [
     // ...
   ]
@@ -43,13 +56,13 @@ export default defineConfig({
 
 ---
 
-### rename (optional, default true)
+## rename (optional, default true)
 
 You can define by default if the files are renamed or not.
 
 ```typescript
 export default defineConfig({
-  rename: false, // [!code focus],
+  rename: false, // [!code focus]
   converters: [
     // ...
   ]
@@ -58,7 +71,7 @@ export default defineConfig({
 
 ---
 
-### bin (optional)
+## bin (optional)
 
 You may set the ffmpeg and ffprobe binary paths manually:
 

docs/guide/model-setup.md docs/guide/basic_usage/model-setup.md

@@ -4,6 +4,6 @@ The `adonis-attachment` package was designed to simplify file upload management.
 
 The creation of variants is handled through Converters.
 
-<!--@include: ./partials/table-converter.md-->
+<!--@include: ../partials/table-converter.md-->
 
 Project sample : [adonis-starter-kit](https://github.com/batosai/adonis-starter-kit) 

docs/guide/view-setup.md docs/guide/basic_usage/view-setup.md

@@ -9,7 +9,7 @@ hero:
   actions:
     - theme: brand
       text: Getting started
-      link: /guide/introduction
+      link: /guide/essentials/introduction
     - theme: alt
       text: View on GitHub
       link: https://github.com/batosai/adonis-attachment
@@ -19,7 +19,7 @@ features:
     details: Simplifying upload management.
   - title: Convert
     details: Optimise, convert, crop image, thumbnail video etc.
-  - title: Custom
-    details: Go further and create your own converter.
+  - title: Edge & inertia compliant
+    details: Go to attachment in your favorite frontend
 ---
 

docs/guide/configuration.md docs/guide/essentials/configuration.md

@@ -12,6 +12,7 @@ Meta data list (if available):
 - orientation
 - mime type
 - gps
+- url
 
 Sample struture JSON in database
 
@@ -42,6 +43,7 @@ Sample struture JSON in database
   "mimeType":"image/jpeg",
   "path":"uploads/avatars/xjfpa4tuxh66p6s3hrgl0pzn.jpg",
   "originalName":"aco_bot.jpg",
+  "url": "/uploads/avatars/[...]", 
   "variants":[
     {
       "key":"thumbnail",
@@ -62,7 +64,8 @@ Sample struture JSON in database
         }
       },
       "mimeType":"image/webp",
-      "path":"uploads/avatars/variants/xjfpa4tuxh66p6s3hrgl0pzn.jpg/ajtugq7224qp9moqyi216vur.webp"
+      "path":"uploads/avatars/variants/xjfpa4tuxh66p6s3hrgl0pzn.jpg/ajtugq7224qp9moqyi216vur.webp",
+      "url": "/uploads/avatars/variants/[...]", 
     }
   ]
 }