feat(api): expose Resource class (#8370)

* feat(api): expose `Resource` class

continuation of https://github.com/tauri-apps/tauri/pull/8276

* Apply suggestions from code review

* fmt

---------

Co-authored-by: Lucas Fernandes Nogueira <lucas@tauri.app>
Co-authored-by: Lucas Nogueira <lucas@tauri.studio>

.changes/api-Resource.md

@@ -0,0 +1,5 @@
+---
+'@tauri-apps/api': 'patch:feat'
+---
+
+Exposed `Resource` class which should be extended for Rust-backed resources created through `tauri::Manager::resources_table`.

.changes/tauri-resources-table.md

@@ -2,4 +2,4 @@
 'tauri': 'patch:feat'
 ---
 
-Exposed `Manager::resources_table` to access the resources table used by tauri, which could be used by plugins or app authors to store their resources and retrieve it later using an id.
+Exposed `Manager::resources_table` to access the resources table used by tauri, which could be used by plugins or app authors to store their resources and retrieve it later using an id and can be used to create Rust-backed resources in JS.

tooling/api/src/core.ts

@@ -160,6 +160,50 @@ function convertFileSrc(filePath: string, protocol = 'asset'): string {
   return window.__TAURI_INTERNALS__.convertFileSrc(filePath, protocol)
 }
 
+/**
+ * A rust-backed resource stored through `tauri::Manager::resources_table` API.
+ *
+ * The resource lives in the main process and does not exist
+ * in the Javascript world, and thus will not be cleaned up automatiacally
+ * except on application exit. If you want to clean it up early, call {@linkcode Resource.close}
+ *
+ * @example
+ * ```typescript
+ * import { Resource, invoke } from '@tauri-apps/api/core';
+ * export class DatabaseHandle extends Resource {
+ *   static async open(path: string): Promise<DatabaseHandle> {
+ *     const rid: number = await invoke('open_db', { path });
+ *     return new DatabaseHandle(rid);
+ *   }
+ *
+ *   async execute(sql: string): Promise<void> {
+ *     await invoke('execute_sql', { rid: this.rid, sql });
+ *   }
+ * }
+ * ```
+ */
+export class Resource {
+  readonly #rid: number
+
+  get rid(): number {
+    return this.#rid
+  }
+
+  constructor(rid: number) {
+    this.#rid = rid
+  }
+
+  /**
+   * Destroys and cleans up this resource from memory.
+   * **You should not call any method on this object anymore and should drop any reference to it.**
+   */
+  async close(): Promise<void> {
+    return invoke('plugin:resources|close', {
+      rid: this.rid
+    })
+  }
+}
+
 export type { InvokeArgs, InvokeOptions }
 
 export {

tooling/api/src/internal/index.ts

@@ -1,34 +0,0 @@
-// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-License-Identifier: MIT
-
-import { invoke } from '../core'
-
-/**
- * A rust-backed resource.
- *
- * The resource lives in the main process and does not exist
- * in the Javascript world, and thus will not be cleaned up automatiacally
- * except on application exit. If you want to clean it up early, call {@linkcode Resource.close}
- */
-export class Resource {
-  readonly #rid: number
-
-  get rid(): number {
-    return this.#rid
-  }
-
-  constructor(rid: number) {
-    this.#rid = rid
-  }
-
-  /**
-   * Destroys and cleans up this resource from memory.
-   * **You should not call any method on this object anymore and should drop any reference to it.**
-   */
-  async close(): Promise<void> {
-    return invoke('plugin:resources|close', {
-      rid: this.rid
-    })
-  }
-}

tooling/api/src/menu/base.ts

@@ -2,8 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
-import { Resource } from '../internal'
-import { Channel, invoke } from '../core'
+import { Channel, invoke, Resource } from '../core'
 import { CheckMenuItemOptions } from './checkMenuItem'
 import { IconMenuItemOptions } from './iconMenuItem'
 import { MenuItemOptions } from './menuItem'

tooling/api/src/tray.ts

@@ -3,8 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { Menu, Submenu } from './menu'
-import { Resource } from './internal'
-import { Channel, invoke } from './core'
+import { Channel, invoke, Resource } from './core'
 
 /**
  * Describes a tray event emitted when a tray icon is clicked