From b1796792134cca7f864fb5d5b29901ebb64dda9c Mon Sep 17 00:00:00 2001
From: Odunayo Mohammed <factman60@gmail.com>
Date: Thu, 20 Nov 2025 01:25:57 +0100
Subject: [PATCH] chore: :sparkles: Refactor PermissionsAPI to extend
 PermissionsCore and improve permission handling

---
 packages/permissions/demo/index.html        | 128 ++++----
 packages/permissions/demo/index.js          |  10 +-
 packages/permissions/src/PermissionsAPI.ts  | 320 ++++----------------
 packages/permissions/src/PermissionsCore.ts | 228 ++++++++++++++
 4 files changed, 366 insertions(+), 320 deletions(-)
 create mode 100644 packages/permissions/src/PermissionsCore.ts

diff --git a/packages/permissions/demo/index.html b/packages/permissions/demo/index.html
index 4f3604d..5df5142 100644
--- a/packages/permissions/demo/index.html
+++ b/packages/permissions/demo/index.html
@@ -5,6 +5,8 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Permissions</title>
+  <link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/styles/atom-one-dark.min.css">
+  <script src="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/highlight.min.js"></script>
   <style>
     html,
     body {
@@ -35,25 +37,11 @@
       cursor: pointer;
     }
 
-    .code-container pre {
-      background-color: #3a3a3a;
-      border-radius: 5px;
-      padding: 1em;
-      color: cyan;
-      margin: 0;
-      display: block;
-      font-family: monospace;
-    }
-
     .code-container p {
       margin: 0 0 0.5em;
       text-decoration: underline;
       text-underline-offset: 4px;
     }
-
-    pre span {
-      color: springgreen;
-    }
   </style>
 </head>
 
@@ -109,69 +97,82 @@ <h2>PermissionsAPI Usage Examples</h2>
   <div class="code-container">
     <p onclick="toggleCodeView(this)">PermissionsAPI.isSupported</p>
     <pre id="isSupported" style="display: none;">
-<span>// Checks if the Permissions API is supported in the current browser/environment.</span>
+      <code class="language-javascript">
+// Checks if the Permissions API is supported in the current browser/environment.
+
+const permissions = new PermissionsAPI()
 
-const support = PermissionsAPI.isSupported()
-console.log(support) <span>// True or False</span>
+const support = permissions.isSupported()
+console.log(support) // True or False
 
-<hr/>
-<span>// Exception example</span>
+// Exception example
 
 try {
-  const support = PermissionsAPI.isSupported(true)
-  console.log(support) <span>// True</span>
+  const support = permissions.isSupported(true)
+  console.log(support) // True
   ...
 } catch(error) {
-  console.log(error.message) <span>// Permissions API is not supported in this browser/environment.</span>
+  console.log(error.message) // Permissions API is not supported in this browser/environment.
 }
-</pre>
+      </code>
+    </pre>
   </div>
 
   <div class="code-container">
     <p onclick="toggleCodeView(this)">PermissionsAPI.getPermission</p>
     <pre id="getPermission" style="display: none;">
-<span>// Promise example</span>
+      <code class="language-javascript">
+// Promise example
+
+const permissions = new PermissionsAPI()
 
-PermissionsAPI.getPermission({ name: 'geolocation' })
+permissions.getPermission({ name: 'geolocation' })
   .then(({ error, permission }) => {
     if (error) {
       console.error('Error fetching permission status:', error.message)
       return
     }
     if (permission.state === 'denied') {
-      <span>// can't use geolocation service, notify the user</span>
+      // can't use geolocation service, notify the user
       console.log('permission:', permission.state)
       return
     }
-    <span>// you can use the geolocation service here</span>
+    // you can use the geolocation service here
     console.log('permission is granted or will prompt the user for access', permission.state)
   })
+      </code>
 
-<hr/>
-<span>// Async await example</span>
+      <code class="language-javascript">
+// Async await example
+
+const permissions = new PermissionsAPI()
 
 async function geolocation() {
-  const { error, permission } = await PermissionsAPI.getPermission({ name: 'geolocation' })
+  const { error, permission } = await permissions.getPermission({ name: 'geolocation' })
 
   if (error) {
     console.error('Error fetching permission status:', error.message)
   } else if (permission.state === 'denied') {
-    <span>// can't use geolocation service, notify the user</span>
+    // can't use geolocation service, notify the user
     console.log('permission:', permission.state)
   } else {
-    <span>// you can use the geolocation service here</span>
+    // you can use the geolocation service here
     console.log('permission is granted or will prompt the user for access', permission.state)
   }
 }
+      </code>
 </pre>
   </div>
 
   <div class="code-container">
     <p onclick="toggleCodeView(this)">PermissionsAPI.getPermissionHandler</p>
     <pre id="getPermissionHandler" style="display: none;">
-<span>// Callback example</span>
+      <code class="language-javascript">
+// Callback example
+
+const permissions = new PermissionsAPI()
 
-const notificationHandler = PermissionsAPI.getPermissionHandler(
+const notificationHandler = permissions.createHandler(
   { name: 'notifications' },
   {
     granted: (permission) => {
@@ -187,16 +188,19 @@ <h2>PermissionsAPI Usage Examples</h2>
   }
 )
 
-<span>// Initiate the handler by calling the handler function</span>
+// Initiate the handler by calling the handler function
 notificationHandler.getPermission()
+      </code>
 
-<hr/>
-<span>// Event handling example</span>
+      <code class="language-javascript">
+// Event handling example
 
-const notificationHandler = PermissionsAPI.getPermissionHandler({ name: 'notifications' })
+const permissions = new PermissionsAPI()
+
+const notificationHandler = permissions.createHandler({ name: 'notifications' })
 
 notificationHandler.onPermissionChange((permission) => {
-  console.log('User change permission:', permission.state) <span>// granted or denied</span>
+  console.log('User change permission:', permission.state) // granted or denied
 })
 notificationHandler.onPermissionGranted((permission) => {
   console.log('Permission:', permission.state)
@@ -209,13 +213,16 @@ <h2>PermissionsAPI Usage Examples</h2>
   console.error('Permission error:', error)
 })
 
-<span>// Initiate the handler by calling the handler function</span>
+// Initiate the handler by calling the handler function
 notificationHandler.getPermission()
+      </code>
+
+      <code class="language-javascript">
+// Callback and Event example
 
-<hr />
-<span>// Callback and Event example</span>
+const permissions = new PermissionsAPI()
 
-const notificationHandler = PermissionsAPI.getPermissionHandler(
+const notificationHandler = permissions.createHandler(
   { name: 'notifications' },
   {
     granted: (permission) => {
@@ -232,20 +239,24 @@ <h2>PermissionsAPI Usage Examples</h2>
 )
 
 notificationHandler.onPermissionChange((permission) => {
-  console.log('User change permission:', permission.state) <span>// granted or denied</span>
+  console.log('User change permission:', permission.state) // granted or denied
 })
 
-<span>// Initiate the handler by calling the handler function</span>
+// Initiate the handler by calling the handler function
 notificationHandler.getPermission()
+      </code>
 </pre>
   </div>
 
   <div class="code-container">
     <p onclick="toggleCodeView(this)">PermissionsAPI.getAsyncPermissionHandler</p>
     <pre id="getAsyncPermissionHandler" style="display: none;">
-<span>// Promise example</span>
+      <code class="language-javascript">
+// Promise example
 
-const asyncCameraHandler = PermissionsAPI.getAsyncPermissionHandler({ name: 'camera' })
+const permissions = new PermissionsAPI()
+
+const asyncCameraHandler = permissions.createAsyncHandler({ name: 'camera' })
 asyncCameraHandler.getPermission().then(({ error, permission }) => {
   if (error) {
     asyncCameraHandler.close()
@@ -259,12 +270,16 @@ <h2>PermissionsAPI Usage Examples</h2>
     console.log('Permission:', permission.state)
   }
 })
+      </code>
+
+      <code class="language-javascript">
 
-<hr/>
-<span>// Async await example</span>
+// Async await example
+
+const permissions = new PermissionsAPI()
 
 async function camera() {
-  const asyncCameraHandler = PermissionsAPI.getAsyncPermissionHandler({ name: 'camera' })
+  const asyncCameraHandler = permissions.createAsyncHandler({ name: 'camera' })
   const { error, permission } = await asyncCameraHandler.getPermission()
 
   if (error) {
@@ -276,15 +291,18 @@ <h2>PermissionsAPI Usage Examples</h2>
     console.log('Permission:', permission.state)
   }
 }
+      </code>
+
+      <code class="language-javascript">
+// Event example
 
-<hr />
-<span>// Event example</span>
+const permissions = new PermissionsAPI()
 
 async function camera() {
-  const asyncCameraHandler = PermissionsAPI.getAsyncPermissionHandler({ name: 'camera' })
+  const asyncCameraHandler = permissions.createAsyncHandler({ name: 'camera' })
 
   asyncCameraHandler.onPermissionChange((permission) => {
-    console.log('User change permission:', permission.state) <span>// granted or denied</span>
+    console.log('User change permission:', permission.state) // granted or denied
   })
 
   const { error, permission } = await asyncCameraHandler.getPermission()
@@ -298,9 +316,11 @@ <h2>PermissionsAPI Usage Examples</h2>
     console.log('Permission:', permission.state)
   }
 }
+      </code>
 </pre>
   </div>
 
+  <script>hljs.highlightAll();</script>
   <script type="module" src="index.js"></script>
   <script>
     function toggleCodeView($this) {
diff --git a/packages/permissions/demo/index.js b/packages/permissions/demo/index.js
index 1ca14a8..64fe6be 100644
--- a/packages/permissions/demo/index.js
+++ b/packages/permissions/demo/index.js
@@ -1,6 +1,6 @@
 import { PermissionsAPI } from '../dist/permissions.js'
 
-const { isSupported, permissionNames, getPermissionHandler } = PermissionsAPI
+const permissions = new PermissionsAPI()
 
 function createCodeTag(text, color = '#e3e3e3') {
   const code = document.createElement('code')
@@ -49,7 +49,7 @@ const stateColor = {
 }
 
 function handlePermission(option) {
-  permissionHandler = getPermissionHandler(option, {
+  permissionHandler = permissions.createHandler(option, {
     granted: (permission) => {
       console.log('Permission Granted:', permission)
       state.replaceChildren(
@@ -84,15 +84,15 @@ function handlePermission(option) {
 
 document
   .querySelector('#support')
-  .appendChild(createCodeTag(isSupported().toString()))
+  .appendChild(createCodeTag(permissions.isSupported().toString()))
 document
   .querySelector('#names')
-  .append(...permissionNames.map((name) => createCodeTag(name)))
+  .append(...PermissionsAPI.permissionNames.map((name) => createCodeTag(name)))
 
 const selectPermissions = [
   'unsupported-permission',
   'invalid-permission',
-  ...permissionNames
+  ...PermissionsAPI.permissionNames
 ]
 const select = document.querySelector('#select')
 select.append(...selectPermissions.map(createOptionTag))
diff --git a/packages/permissions/src/PermissionsAPI.ts b/packages/permissions/src/PermissionsAPI.ts
index c80e787..3f8aaf3 100644
--- a/packages/permissions/src/PermissionsAPI.ts
+++ b/packages/permissions/src/PermissionsAPI.ts
@@ -1,6 +1,6 @@
+import { PermissionsCore } from './PermissionsCore'
 import type {
   AsyncPermissionHandler,
-  HandlerEvents,
   PermissionHandler,
   PermissionHandlerOption,
   PermissionOption,
@@ -20,13 +20,14 @@ import type {
  *
  * @class PermissionsAPI
  */
-export class PermissionsAPI {
+export class PermissionsAPI extends PermissionsCore {
   /**
    * Permission names of permissions api
    * @public
    * @static
+   * @readonly
    */
-  static permissionNames = [
+  static readonly permissionNames = [
     'background-sync',
     'geolocation',
     'local-fonts',
@@ -50,37 +51,31 @@ export class PermissionsAPI {
     'clipboard-write'
   ] as const
 
-  /**
-   * A reference to the Permissions API provided by the browser.
-   * @private
-   * @static
-   * @type {Permissions}
-   */
-  static #permissions = navigator.permissions
+  constructor() {
+    super()
+  }
 
   /**
-   * A weak map to manage event listeners for permission handlers.
-   * @private
-   * @static
-   * @type {WeakMap<(PermissionHandler<void> | AsyncPermissionHandler), HandlerEvents>}
+   * A convenient way to get the browser permissions instance
+   *
+   * @returns {Permissions} `navigator.permissions`
    */
-  static #events = new WeakMap<
-    PermissionHandler | AsyncPermissionHandler,
-    HandlerEvents
-  >()
+  getNativePermissionsInstance(): Permissions {
+    return this.permissions
+  }
 
   /**
    * Checks if the Permissions API is supported in the current browser/environment.
    * If throwError is true and the Permissions API is not supported, an error is thrown.
    *
    * @param {boolean} [throwError=false] - If true, throws an error if the Permissions API is not supported.
-   * @returns {boolean} - True if the Permissions API is supported, false otherwise.
+   * @returns {boolean} True if the Permissions API is supported, false otherwise.
    * @throws {Error}
    */
-  static isSupported(): boolean
-  static isSupported(throwError: boolean): boolean
-  static isSupported(throwError = false) {
-    const supported = !!PermissionsAPI.#permissions
+  isSupported(): boolean
+  isSupported(throwError: boolean): boolean
+  isSupported(throwError = false) {
+    const supported = !!this.permissions
     if (!supported && throwError) {
       throw new Error(
         'Permissions API is not supported in this browser/environment.'
@@ -94,10 +89,11 @@ export class PermissionsAPI {
    * @async
    * Gets the permission status for any valid permission name provided in the option object.
    * @param {PermissionOption} option - Permission request option.
-   * @returns {Promise<PermissionResponse>} - A promise that resolves to the permission response or an error response.
+   * @returns {Promise<PermissionResponse>} A promise that resolves to the permission response or an error response.
    *
    * @example
-   * PermissionsAPI.getPermission({ name: 'geolocation' })
+   * const permissions = new PermissionsAPI()
+   * permissions.getPermission({ name: 'geolocation' })
    *  .then(({ error, permission }) => {
    *    if (error) {
    *      console.error('Error fetching permission status:', error.message)
@@ -113,7 +109,8 @@ export class PermissionsAPI {
    *  })
    *
    * @example
-   * const { error, permission } = await PermissionsAPI.getPermission({ name: 'geolocation' })
+   * const permissions = new PermissionsAPI()
+   * const { error, permission } = await permissions.getPermission({ name: 'geolocation' })
    * if (error) {
    *  console.error('Error fetching permission status:', error.message)
    * } else if (permission.state === 'denied') {
@@ -124,140 +121,22 @@ export class PermissionsAPI {
    *   console.log('permission is granted or will prompt the user for access', permission.state)
    * }
    */
-  static async getPermission(
-    option: PermissionOptionBase
-  ): Promise<PermissionResponse>
-  static async getPermission(
-    option: PermissionOptionMidi
-  ): Promise<PermissionResponse>
-  static async getPermission(
-    option: PermissionOptionPush
-  ): Promise<PermissionResponse>
-  static async getPermission(
-    option: PermissionOption
-  ): Promise<PermissionResponse> {
-    try {
-      const _status = await PermissionsAPI.#permissions.query(
-        option as PermissionDescriptor
-      )
-
-      return { error: null, permission: _status }
-    } catch (error) {
-      if (error.name === 'TypeError') {
-        return {
-          error: {
-            state: 'unsupported',
-            name: error.name,
-            message: error.message
-          },
-          permission: null
-        }
-      }
-
-      return {
-        error: { state: 'invalid', name: error.name, message: error.message },
-        permission: null
-      }
-    }
-  }
-
-  /**
-   * Retrieves a handler for synchronous permission requests.
-   * @private
-   * @static
-   * @param {PermissionOption} permissionOption - The permission option to request.
-   * @param {PermissionHandlerOption} [handlerOption] - Optional handler options for granted/denied/error callbacks.
-   * @returns {PermissionHandler} - A permission handler for synchronous requests.
-   */
-  static #getHandler(permissionOption: PermissionOptionBase): PermissionHandler
-  static #getHandler(
-    permissionOption: PermissionOptionBase,
-    handlerOption: PermissionHandlerOption
-  ): PermissionHandler
-  static #getHandler(permissionOption: PermissionOptionMidi): PermissionHandler
-  static #getHandler(
-    permissionOption: PermissionOptionMidi,
-    handlerOption: PermissionHandlerOption
-  ): PermissionHandler
-  static #getHandler(permissionOption: PermissionOptionPush): PermissionHandler
-  static #getHandler(
-    permissionOption: PermissionOptionPush,
-    handlerOption: PermissionHandlerOption
-  ): PermissionHandler
-  static #getHandler(
-    permissionOption: PermissionOption,
-    handlerOption?: PermissionHandlerOption
-  ): PermissionHandler {
-    let _handler: PermissionHandler = {
-      close: () => {
-        if (_handler) {
-          const _events = PermissionsAPI.#events.get(_handler)
-          if (_events.permission) {
-            _events.permission.removeEventListener('change', _events.eventListener)
-          }
-          PermissionsAPI.#events.delete(_handler)
-          _handler = null
-        }
-      },
-      getPermission: () => {
-        const _events = PermissionsAPI.#events.get(_handler)
-
-        if (!_events || _handler === null) throw new Error('Cannot get permission: handler has been closed')
-
-        PermissionsAPI.getPermission(permissionOption).then(
-          ({ error, permission }) => {
-            if (error) {
-              if (_events.onPermissionError) _events.onPermissionError(error)
-              if (handlerOption?.error) handlerOption.error(error)
-              return
-            }
-
-            if (_events.permission) {
-              _events.permission.removeEventListener('change', _events.eventListener)
-            }
-
-            _events.permission = permission
-            _events.eventListener = () => {
-              if (permission.state === 'denied') {
-                if (_events.onPermissionDenied)
-                  _events.onPermissionDenied(permission)
-              } else {
-                if (_events.onPermissionGranted)
-                  _events.onPermissionGranted(permission)
-              }
-              if (_events.onPermissionChange) {
-                _events.onPermissionChange(permission)
-              }
-            }
-
-            permission.addEventListener('change', _events.eventListener)
-
-            if (permission.state === 'denied') {
-              if (_events.onPermissionDenied)
-                _events.onPermissionDenied(permission)
-              if (handlerOption?.denied) handlerOption.denied(permission)
-            } else {
-              if (_events.onPermissionGranted)
-                _events.onPermissionGranted(permission)
-              if (handlerOption?.granted) handlerOption.granted(permission)
-            }
-          }
-        )
-      }
-    }
-    PermissionsAPI.#events.set(_handler, {})
-
-    return _handler
+  async getPermission(option: PermissionOptionBase): Promise<PermissionResponse>
+  async getPermission(option: PermissionOptionMidi): Promise<PermissionResponse>
+  async getPermission(option: PermissionOptionPush): Promise<PermissionResponse>
+  async getPermission(option: PermissionOption): Promise<PermissionResponse> {
+    return this.queryPermission(option)
   }
 
   /**
    * Creates a permission handler for synchronous permission requests.
    * @param {PermissionOption} permissionOption - The permission option to request.
    * @param {PermissionHandlerOption} [handlerOption] - Optional handler options for granted/denied/error callbacks.
-   * @returns {PermissionHandler} - A permission handler for synchronous requests.
+   * @returns {PermissionHandler} A permission handler for synchronous requests.
    *
    * @example
-   * const notificationHandler = PermissionsAPI.getPermissionHandler(
+   * const permissions = new PermissionsAPI()
+   * const notificationHandler = permissions.createHandler(
    *  { name: 'notifications' },
    *  {
    *    granted: (permission) => {
@@ -277,7 +156,8 @@ export class PermissionsAPI {
    * notificationHandler.getPermission()
    *
    * @example
-   * const notificationHandler = PermissionsAPI.getPermissionHandler({
+   * const permissions = new PermissionsAPI()
+   * const notificationHandler = permissions.createHandler({
    *   name: 'notifications'
    * })
    *
@@ -298,136 +178,53 @@ export class PermissionsAPI {
    * // Initiate the handler by calling the handler function
    * notificationHandler.getPermission()
    */
-  static getPermissionHandler(
-    permissionOption: PermissionOptionBase
-  ): PermissionHandler
-  static getPermissionHandler(
+  createHandler(permissionOption: PermissionOptionBase): PermissionHandler
+  createHandler(
     permissionOption: PermissionOptionBase,
     handlerOption?: PermissionHandlerOption
   ): PermissionHandler
-  static getPermissionHandler(
-    permissionOption: PermissionOptionMidi
-  ): PermissionHandler
-  static getPermissionHandler(
+  createHandler(permissionOption: PermissionOptionMidi): PermissionHandler
+  createHandler(
     permissionOption: PermissionOptionMidi,
     handlerOption?: PermissionHandlerOption
   ): PermissionHandler
-  static getPermissionHandler(
-    permissionOption: PermissionOptionPush
-  ): PermissionHandler
-  static getPermissionHandler(
+  createHandler(permissionOption: PermissionOptionPush): PermissionHandler
+  createHandler(
     permissionOption: PermissionOptionPush,
     handlerOption?: PermissionHandlerOption
   ): PermissionHandler
-  static getPermissionHandler(
+  createHandler(
     permissionOption: PermissionOption,
     handlerOption?: PermissionHandlerOption
   ): PermissionHandler {
-    const handler: PermissionHandler = PermissionsAPI.#getHandler(
+    const handler: PermissionHandler = this.getHandler(
       permissionOption,
       handlerOption
     )
     handler.onPermissionChange = (callback) => {
-      PermissionsAPI.#events.get(handler).onPermissionChange = callback
+      this.events.get(handler).onPermissionChange = callback
     }
     handler.onPermissionGranted = (callback) => {
-      PermissionsAPI.#events.get(handler).onPermissionGranted = callback
+      this.events.get(handler).onPermissionGranted = callback
     }
     handler.onPermissionDenied = (callback) => {
-      PermissionsAPI.#events.get(handler).onPermissionDenied = callback
+      this.events.get(handler).onPermissionDenied = callback
     }
     handler.onPermissionError = (callback) => {
-      PermissionsAPI.#events.get(handler).onPermissionError = callback
+      this.events.get(handler).onPermissionError = callback
     }
 
     return Object.freeze(handler)
   }
 
-  /**
-   * Retrieves a handler for asynchronous permission requests.
-   * @private
-   * @static
-   * @param {PermissionOption} permissionOption - The permission option to request.
-   * @returns {AsyncPermissionHandler} - A permission handler for asynchronous requests.
-   */
-  static #getAsyncHandler(
-    permissionOption: PermissionOptionBase
-  ): AsyncPermissionHandler
-  static #getAsyncHandler(
-    permissionOption: PermissionOptionMidi
-  ): AsyncPermissionHandler
-  static #getAsyncHandler(
-    permissionOption: PermissionOptionPush
-  ): AsyncPermissionHandler
-  static #getAsyncHandler(
-    permissionOption: PermissionOption
-  ): AsyncPermissionHandler {
-    let _handler: AsyncPermissionHandler = {
-      close: () => {
-        if (_handler) {
-          const _events = PermissionsAPI.#events.get(_handler)
-          if (_events.permission) {
-            _events.permission.removeEventListener('change', _events.eventListener)
-          }
-          PermissionsAPI.#events.delete(_handler)
-          _handler = null
-        }
-      },
-      getPermission: async (): Promise<PermissionResponse> => {
-        const _events = PermissionsAPI.#events.get(_handler)
-
-        const { error, permission } =
-          await PermissionsAPI.getPermission(permissionOption)
-        if (error) {
-          if (_events.onPermissionError) _events.onPermissionError(error)
-
-          return { error, permission: null }
-        }
-
-        if (_events.permission) {
-          _events.permission.removeEventListener('change', _events.eventListener)
-        }
-
-        _events.permission = permission
-        _events.eventListener = () => {
-          if (permission.state === 'denied') {
-            if (_events.onPermissionDenied)
-              _events.onPermissionDenied(permission)
-          } else {
-            if (_events.onPermissionGranted)
-              _events.onPermissionGranted(permission)
-          }
-          if (_events.onPermissionChange) {
-            _events.onPermissionChange(permission)
-          }
-        }
-
-        permission.addEventListener('change', _events.eventListener)
-
-        if (permission.state === 'denied') {
-          if (_events.onPermissionDenied) _events.onPermissionDenied(permission)
-
-          return { error: null, permission }
-        } else {
-          if (_events.onPermissionGranted)
-            _events.onPermissionGranted(permission)
-
-          return { error: null, permission }
-        }
-      }
-    }
-    PermissionsAPI.#events.set(_handler, {})
-
-    return _handler
-  }
-
   /**
    * Creates a permission handler for asynchronous permission requests.
    * @param {PermissionOption} permissionOption - The permission option to request.
-   * @returns {AsyncPermissionHandler} - A permission handler for asynchronous requests.
+   * @returns {AsyncPermissionHandler} A permission handler for asynchronous requests.
    *
    * @example
-   * const asyncCameraHandler = PermissionsAPI.getAsyncPermissionHandler({ name: 'camera' })
+   * const permissions = new PermissionsAPI()
+   * const asyncCameraHandler = permissions.createAsyncHandler({ name: 'camera' })
    * asyncCameraHandler.getPermission()
    *   .then(({ error, permission }) => {
    *     if (error) {
@@ -443,7 +240,8 @@ export class PermissionsAPI {
    *   })
    *
    * @example
-   * const asyncCameraHandler = PermissionsAPI.getAsyncPermissionHandler({ name: 'camera' })
+   * const permissions = new PermissionsAPI()
+   * const asyncCameraHandler = permissions.createAsyncHandler({ name: 'camera' })
    * const { error, permission } = await asyncCameraHandler.getPermission()
    * if (error) {
    *   console.error('Async permission error:', error)
@@ -453,31 +251,31 @@ export class PermissionsAPI {
    *   console.log('Permission:', permission.state)
    * }
    */
-  static getAsyncPermissionHandler(
+  createAsyncHandler(
     permissionOption: PermissionOptionBase
   ): AsyncPermissionHandler
-  static getAsyncPermissionHandler(
+  createAsyncHandler(
     permissionOption: PermissionOptionMidi
   ): AsyncPermissionHandler
-  static getAsyncPermissionHandler(
+  createAsyncHandler(
     permissionOption: PermissionOptionPush
   ): AsyncPermissionHandler
-  static getAsyncPermissionHandler(
+  createAsyncHandler(
     permissionOption: PermissionOption
   ): AsyncPermissionHandler {
     const handler: AsyncPermissionHandler =
-      PermissionsAPI.#getAsyncHandler(permissionOption)
+      this.getAsyncHandler(permissionOption)
     handler.onPermissionChange = function (callback) {
-      PermissionsAPI.#events.get(handler).onPermissionChange = callback
+      this.events.get(handler).onPermissionChange = callback
     }
     handler.onPermissionGranted = function (callback) {
-      PermissionsAPI.#events.get(handler).onPermissionGranted = callback
+      this.events.get(handler).onPermissionGranted = callback
     }
     handler.onPermissionDenied = function (callback) {
-      PermissionsAPI.#events.get(handler).onPermissionDenied = callback
+      this.events.get(handler).onPermissionDenied = callback
     }
     handler.onPermissionError = function (callback) {
-      PermissionsAPI.#events.get(handler).onPermissionError = callback
+      this.events.get(handler).onPermissionError = callback
     }
 
     return Object.freeze(handler)
diff --git a/packages/permissions/src/PermissionsCore.ts b/packages/permissions/src/PermissionsCore.ts
new file mode 100644
index 0000000..a24c804
--- /dev/null
+++ b/packages/permissions/src/PermissionsCore.ts
@@ -0,0 +1,228 @@
+import type {
+  AsyncPermissionHandler,
+  HandlerEvents,
+  PermissionHandler,
+  PermissionHandlerOption,
+  PermissionOption,
+  PermissionResponse
+} from './types'
+
+/**
+ * The core integration of the browser permissions
+ *
+ * @class PermissionsCore
+ */
+export abstract class PermissionsCore {
+  /**
+   * A reference to the Permissions API provided by the browser.
+   * @protected
+   * @readonly
+   * @type {Permissions}
+   */
+  protected readonly permissions: Permissions
+
+  /**
+   * A weak map to manage event listeners for permission handlers.
+   * @protected
+   * @readonly
+   * @type {WeakMap<(PermissionHandler<void> | AsyncPermissionHandler), HandlerEvents>}
+   */
+  protected readonly events: WeakMap<
+    PermissionHandler | AsyncPermissionHandler,
+    HandlerEvents
+  >
+
+  constructor() {
+    this.permissions = navigator.permissions
+    this.events = new WeakMap<
+      PermissionHandler | AsyncPermissionHandler,
+      HandlerEvents
+    >()
+  }
+
+  /**
+   * @async
+   * Queries permission status for any valid permission name provided in the option object.
+   * @param {PermissionOption} option - Permission request option.
+   * @returns {Promise<PermissionResponse>} A promise that resolves to the permission response or an error response.
+   */
+  protected async queryPermission(
+    option: PermissionOption
+  ): Promise<PermissionResponse> {
+    try {
+      const _status = await this.permissions.query(
+        option as PermissionDescriptor
+      )
+
+      return { error: null, permission: _status }
+    } catch (error) {
+      if (error.name === 'TypeError') {
+        return {
+          error: {
+            state: 'unsupported',
+            name: error.name,
+            message: error.message
+          },
+          permission: null
+        }
+      }
+
+      return {
+        error: { state: 'invalid', name: error.name, message: error.message },
+        permission: null
+      }
+    }
+  }
+
+  /**
+   * Retrieves a handler for synchronous permission requests.
+   * @protected
+   * @param {PermissionOption} permissionOption - The permission option to request.
+   * @param {PermissionHandlerOption} [handlerOption] - Optional handler options for granted/denied/error callbacks.
+   * @returns {PermissionHandler} A permission handler for synchronous requests.
+   */
+  protected getHandler(
+    permissionOption: PermissionOption,
+    handlerOption?: PermissionHandlerOption
+  ): PermissionHandler {
+    let _handler: PermissionHandler = {
+      close: () => {
+        if (_handler) {
+          const _events = this.events.get(_handler)
+          if (_events.permission) {
+            _events.permission.removeEventListener(
+              'change',
+              _events.eventListener
+            )
+          }
+          this.events.delete(_handler)
+          _handler = null
+        }
+      },
+      getPermission: () => {
+        const _events = this.events.get(_handler)
+
+        if (!_events || _handler === null)
+          throw new Error('Cannot get permission: handler has been closed')
+
+        this.queryPermission(permissionOption).then(({ error, permission }) => {
+          if (error) {
+            if (_events.onPermissionError) _events.onPermissionError(error)
+            if (handlerOption?.error) handlerOption.error(error)
+            return
+          }
+
+          if (_events.permission) {
+            _events.permission.removeEventListener(
+              'change',
+              _events.eventListener
+            )
+          }
+
+          _events.permission = permission
+          _events.eventListener = () => {
+            if (permission.state === 'denied') {
+              if (_events.onPermissionDenied)
+                _events.onPermissionDenied(permission)
+            } else {
+              if (_events.onPermissionGranted)
+                _events.onPermissionGranted(permission)
+            }
+            if (_events.onPermissionChange) {
+              _events.onPermissionChange(permission)
+            }
+          }
+
+          permission.addEventListener('change', _events.eventListener)
+
+          if (permission.state === 'denied') {
+            if (_events.onPermissionDenied)
+              _events.onPermissionDenied(permission)
+            if (handlerOption?.denied) handlerOption.denied(permission)
+          } else {
+            if (_events.onPermissionGranted)
+              _events.onPermissionGranted(permission)
+            if (handlerOption?.granted) handlerOption.granted(permission)
+          }
+        })
+      }
+    }
+    this.events.set(_handler, {})
+
+    return _handler
+  }
+
+  /**
+   * Retrieves a handler for asynchronous permission requests.
+   * @protected
+   * @param {PermissionOption} permissionOption - The permission option to request.
+   * @returns {AsyncPermissionHandler} A permission handler for asynchronous requests.
+   */
+  protected getAsyncHandler(
+    permissionOption: PermissionOption
+  ): AsyncPermissionHandler {
+    let _handler: AsyncPermissionHandler = {
+      close: () => {
+        if (_handler) {
+          const _events = this.events.get(_handler)
+          if (_events.permission) {
+            _events.permission.removeEventListener(
+              'change',
+              _events.eventListener
+            )
+          }
+          this.events.delete(_handler)
+          _handler = null
+        }
+      },
+      getPermission: async (): Promise<PermissionResponse> => {
+        const _events = this.events.get(_handler)
+
+        const { error, permission } =
+          await this.queryPermission(permissionOption)
+        if (error) {
+          if (_events.onPermissionError) _events.onPermissionError(error)
+
+          return { error, permission: null }
+        }
+
+        if (_events.permission) {
+          _events.permission.removeEventListener(
+            'change',
+            _events.eventListener
+          )
+        }
+
+        _events.permission = permission
+        _events.eventListener = () => {
+          if (permission.state === 'denied') {
+            if (_events.onPermissionDenied)
+              _events.onPermissionDenied(permission)
+          } else {
+            if (_events.onPermissionGranted)
+              _events.onPermissionGranted(permission)
+          }
+          if (_events.onPermissionChange) {
+            _events.onPermissionChange(permission)
+          }
+        }
+
+        permission.addEventListener('change', _events.eventListener)
+
+        if (permission.state === 'denied') {
+          if (_events.onPermissionDenied) _events.onPermissionDenied(permission)
+
+          return { error: null, permission }
+        } else {
+          if (_events.onPermissionGranted)
+            _events.onPermissionGranted(permission)
+
+          return { error: null, permission }
+        }
+      }
+    }
+    this.events.set(_handler, {})
+
+    return _handler
+  }
+}