@girs/cmenu-3.0 4.4.0 → 4.5.0

package/README.md

@@ -4,82 +4,77 @@
 ![version](https://img.shields.io/npm/v/@girs/cmenu-3.0)
 ![downloads/week](https://img.shields.io/npm/dw/@girs/cmenu-3.0)
 
+GJS TypeScript type definitions for CMenu-3.0 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v4.5.0.
 
-GJS TypeScript type definitions for CMenu-3.0 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v4.4.0.
+This package contains type declarations only. It ships no runtime code, so it adds
+nothing to your program and works with any bundler or none at all.
 
 ## Install
 
-Install the type definitions with npm:
 ```bash
 npm install @girs/cmenu-3.0
 ```
 
-## Usage
+Any package manager works. The package has no dependencies beyond other `@girs/*`
+type packages.
+
+## What it exports
+
+| Import | What you get |
+|---|---|
+| `@girs/cmenu-3.0` | the namespace as a default export, plus the ambient and global declarations |
+| `@girs/cmenu-3.0/ambient` | only the `gi://` module declarations |
+| `@girs/cmenu-3.0/import` | only the `imports.gi` declarations |
+| `@girs/cmenu-3.0/cmenu-3.0` | the namespace, without the side-effecting declarations |
+
+## Three ways to import
+
+Which one you use depends on how you write imports elsewhere, not on your toolchain.
+
+### As a module
 
-Import it like any other module:
 ```ts
 import CMenu from '@girs/cmenu-3.0';
 ```
 
-### Ambient Modules
+### As `gi://`
 
-[Ambient modules](https://github.com/gjsify/ts-for-gir/tree/main/packages/cli#ambient-modules) let you write the same import you would in plain JavaScript.
-For this you need to include `@girs/cmenu-3.0` or `@girs/cmenu-3.0/ambient` in your `tsconfig` or entry point Typescript file:
+GJS resolves `gi://` at runtime. To give it types, reference the package once, either
+from your entry point or from `tsconfig.json`:
 
-`index.ts`:
 ```ts
-import '@girs/cmenu-3.0'
+import '@girs/cmenu-3.0';
 ```
 
-`tsconfig.json`:
 ```json
-{
-  "compilerOptions": {
-    ...
-  },
-  "include": ["@girs/cmenu-3.0"],
-  ...
-}
+{ "include": ["@girs/cmenu-3.0"] }
 ```
 
-The ambient module now resolves with types:
+Then the runtime spelling type-checks:
 
 ```ts
 import CMenu from 'gi://CMenu?version=3.0';
 ```
 
-### Global import
-
-GJS's global `imports.gi` works too, with types.
-For this you need to include `@girs/cmenu-3.0` or `@girs/cmenu-3.0/import` in your `tsconfig` or entry point Typescript file:
+Referencing `@girs/cmenu-3.0/ambient` instead pulls in these declarations
+alone. See [ambient modules](https://github.com/gjsify/ts-for-gir/tree/main/packages/cli#ambient-modules).
 
-`index.ts`:
-```ts
-import '@girs/cmenu-3.0'
-```
-
-`tsconfig.json`:
-```json
-{
-  "compilerOptions": {
-    ...
-  },
-  "include": ["@girs/cmenu-3.0"],
-  ...
-}
-```
+### As `imports.gi`
 
-That form carries types as well:
+GJS's global object works the same way, via `@girs/cmenu-3.0/import`:
 
 ```ts
 const CMenu = imports.gi.CMenu;
 ```
 
-### Bundle
+## Building
 
-Most projects want a bundler. [esbuild](https://esbuild.github.io/) is the smallest thing that works; the [examples directory](https://github.com/gjsify/ts-for-gir/tree/main/examples) has setups for several others.
+The declarations need no build step. If you bundle, every bundler works, since there is
+no runtime code to resolve. The [examples](https://github.com/gjsify/ts-for-gir/tree/main/examples)
+show working setups for several.
 
 ## Other packages
 
-All existing pre-generated packages can be found on [gjsify/types](https://github.com/gjsify/types).
+Every pre-generated package is at [gjsify/types](https://github.com/gjsify/types).
+
 

package/cmenu-3.0.d.ts

@@ -27,15 +27,18 @@ export namespace CMenu {
      * @gir-type Enum
      */
     enum TreeItemType {
-        INVALID,
-        DIRECTORY,
-        ENTRY,
-        SEPARATOR,
-        HEADER,
-        ALIAS,
+        INVALID = 0,
+        DIRECTORY = 1,
+        ENTRY = 2,
+        SEPARATOR = 3,
+        HEADER = 4,
+        ALIAS = 5,
     }
 
 
+    /**
+     * @default :flatpak
+     */
     const DESKTOPAPPINFO_FLATPAK_SUFFIX: string;
 
     /**
@@ -49,13 +52,13 @@ export namespace CMenu {
      * @gir-type Flags
      */
     enum TreeFlags {
-        NONE,
-        INCLUDE_EXCLUDED,
-        SHOW_EMPTY,
-        INCLUDE_NODISPLAY,
-        SHOW_ALL_SEPARATORS,
-        SORT_DISPLAY_NAME,
-        INCLUDE_UNALLOCATED,
+        NONE = 0,
+        INCLUDE_EXCLUDED = 1,
+        SHOW_EMPTY = 256,
+        INCLUDE_NODISPLAY = 2,
+        SHOW_ALL_SEPARATORS = 512,
+        SORT_DISPLAY_NAME = 65536,
+        INCLUDE_UNALLOCATED = 4,
     }
 
 
@@ -273,6 +276,7 @@ export namespace CMenu {
          * application is capable of opening files with the given content type.
          * @param content_type a string.
          * @returns `TRUE` on success, `FALSE` on error.
+         * @throws GLib.Error
          */
         add_supports_type(content_type: string): boolean;
 
@@ -417,6 +421,7 @@ export namespace CMenu {
          * @param files a list of {@link Gio.File} objects
          * @param context the launch context
          * @returns `TRUE` on successful launch, `FALSE` otherwise.
+         * @throws GLib.Error
          */
         launch(files: Gio.File[] | null, context: Gio.AppLaunchContext | null): boolean;
 
@@ -436,6 +441,7 @@ export namespace CMenu {
          * @param uris a list of URIs to launch.
          * @param context the launch context
          * @returns `TRUE` on successful launch, `FALSE` otherwise.
+         * @throws GLib.Error
          */
         launch_uris(uris: string[] | null, context: Gio.AppLaunchContext | null): boolean;
 
@@ -488,6 +494,7 @@ export namespace CMenu {
          * @param result the async result
          * @returns `TRUE` on successful launch, `FALSE` otherwise.
          * @since 2.60
+         * @throws GLib.Error
          */
         launch_uris_finish(result: Gio.AsyncResult): boolean;
 
@@ -495,6 +502,7 @@ export namespace CMenu {
          * Removes a supported type from an application, if possible.
          * @param content_type a string.
          * @returns `TRUE` on success, `FALSE` on error.
+         * @throws GLib.Error
          */
         remove_supports_type(content_type: string): boolean;
 
@@ -502,6 +510,7 @@ export namespace CMenu {
          * Sets the application as the default handler for the given file extension.
          * @param extension a string containing the file extension (without   the dot).
          * @returns `TRUE` on success, `FALSE` on error.
+         * @throws GLib.Error
          */
         set_as_default_for_extension(extension: string): boolean;
 
@@ -509,6 +518,7 @@ export namespace CMenu {
          * Sets the application as the default handler for a given type.
          * @param content_type the content type.
          * @returns `TRUE` on success, `FALSE` on error.
+         * @throws GLib.Error
          */
         set_as_default_for_type(content_type: string): boolean;
 
@@ -519,6 +529,7 @@ export namespace CMenu {
          * application for that content type.
          * @param content_type the content type.
          * @returns `TRUE` on success, `FALSE` on error.
+         * @throws GLib.Error
          */
         set_as_last_used_for_type(content_type: string): boolean;
 
@@ -933,6 +944,7 @@ export namespace CMenu {
          * performs a significant amount of blocking I/O if the
          * tree has not been loaded yet.
          * @returns `true` on success, `false` on error
+         * @throws GLib.Error
          */
         load_sync(): boolean;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@girs/cmenu-3.0",
-    "version": "4.4.0",
+    "version": "4.5.0",
     "description": "GJS TypeScript type definitions for CMenu-3.0",
     "type": "module",
     "module": "cmenu-3.0.js",
@@ -31,11 +31,11 @@
       "test": "tsc --project tsconfig.json"
     },
     "dependencies": {
-      "@girs/gjs": "^4.4.0",
-      "@girs/gio-2.0": "^4.4.0",
-      "@girs/gobject-2.0": "^4.4.0",
-      "@girs/glib-2.0": "^4.4.0",
-      "@girs/gmodule-2.0": "^4.4.0"    },
+      "@girs/gjs": "^4.5.0",
+      "@girs/gio-2.0": "^4.5.0",
+      "@girs/gobject-2.0": "^4.5.0",
+      "@girs/glib-2.0": "^4.5.0",
+      "@girs/gmodule-2.0": "^4.5.0"    },
     "devDependencies": {
       "typescript": "*"
     },