@ts-for-gir/lib 3.0.0-beta.12 → 3.0.0

package/templates/README.md

@@ -0,0 +1,102 @@
+<%# This template is used if the Option `package` is enabled %>
+# <%- packageName %>
+
+<%- PACKAGE_DESC %> using [<%- APP_NAME %>](<%- APP_SOURCE %>) v<%- APP_VERSION %>.
+
+<%_ if (typeof pkgData !== 'undefined' && pkgData.description) { _%>
+<%- pkgData.description %>
+<%_ } _%>
+
+## Install
+
+To use this type definitions, install them with NPM:
+```bash
+npm install <%- npmScope %>/<%- importName %>
+```
+
+<%_ const pkg = dep.get(packageName) _%>
+<%_ if(!pkg){ _%>
+  <%_ return `Package with package name "${packageName}" not found!` _%>
+<%_ } _%>
+## Usage
+
+You can import this package into your project like this:
+```ts
+import <%- pkg.namespace %> from '<%- pkg.importPath %>';
+```
+
+Or if you prefer CommonJS, you can also use this:
+```ts
+const <%- pkg.namespace %> = require('<%- pkg.importPath %>');
+```
+
+### Ambient Modules
+
+You can also use [ambient modules](https://github.com/gjsify/ts-for-gir/tree/main/packages/cli#ambient-modules) to import this module like you would do this in JavaScript.
+For this you need to include `<%- npmScope %>/<%- importName %>` or `<%- npmScope %>/<%- importName %>/<%= environment === 'gjs' ? "ambient" : "import" %>` in your `tsconfig` or entry point Typescript file:
+
+`index.ts`:
+```ts
+import '<%- npmScope %>/<%- importName %>'
+```
+
+`tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    ...
+  },
+  "include": ["<%- npmScope %>/<%- importName %>"],
+  ...
+}
+```
+
+Now you can import the ambient module with TypeScript support: 
+
+<%_ if(environment === 'gjs'){ _%>
+```ts
+import <%= pkg.namespace %> from 'gi://<%= pkg.namespace %>?version=<%= pkg.version %>';
+```
+<%_ } else { _%>
+```ts
+const gi = require('node-gtk')
+const <%= pkg.namespace %> = gi.require('<%= pkg.namespace %>', '<%= pkg.version %>')
+```
+<%_ } _%>
+
+<%_ if(environment === 'gjs'){ _%>
+### Global import
+
+You can also import the module with Typescript support using the global `imports.gi` object of GJS.
+For this you need to include `<%- npmScope %>/<%- importName %>` or `<%- npmScope %>/<%- importName %>/import` in your `tsconfig` or entry point Typescript file:
+
+`index.ts`:
+```ts
+import '<%- npmScope %>/<%- importName %>'
+```
+
+`tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    ...
+  },
+  "include": ["<%- npmScope %>/<%- importName %>"],
+  ...
+}
+```
+
+Now you have also type support for this, too:
+
+```ts
+const <%= pkg.namespace %> = imports.gi.<%= pkg.namespace %>;
+```
+<%_ } _%>
+
+### Bundle
+
+Depending on your project configuration, it is recommended to use a bundler like [esbuild](https://esbuild.github.io/). You can find examples using different bundlers [here](https://github.com/gjsify/ts-for-gir/tree/main/examples).
+
+## Other packages
+
+All existing pre-generated packages can be found on [gjsify/types](https://github.com/gjsify/types).

package/templates/gjs/README-GJS.md

@@ -0,0 +1,109 @@
+<%# This template is used for the README.md of @girs/gjs if the Option `package` is enabled %>
+# <%- packageName %>
+
+<%- PACKAGE_DESC %> using [<%- APP_NAME %>](<%- APP_SOURCE %>) v<%- APP_VERSION %>.
+
+<%_ if (typeof pkgData !== 'undefined' && pkgData.description) { _%>
+<%- pkgData.description %>
+<%_ } else { _%>
+[GJS](https://gitlab.gnome.org/GNOME/gjs) is a JavaScript runtime for the GNOME ecosystem. Using GJS and the type definitions in this NPM package, you can build GTK applications in JavaScript or TypeScript with type checking, better autocompletion and inline documentations.
+<%_ } _%>
+
+## Install
+
+To use this type definitions, install them with NPM:
+```bash
+npm install <%- npmScope %>/<%- importName %>
+```
+
+<%_ const pkg = dep.get(packageName) _%>
+<%_ if(!pkg){ _%>
+  <%_ return `Package with package name "${packageName}" not found!` _%>
+<%_ } _%>
+
+## Usage
+
+You can import this package into your project like this:
+```ts
+import <%- pkg.namespace %> from '<%- pkg.importPath %>';
+```
+
+Or if you prefer CommonJS, you can also use this:
+```ts
+const <%- pkg.namespace %> = require('<%- pkg.importPath %>');
+```
+
+### Global types
+
+After the import, the global types of GJS are also available:
+
+```ts
+console.log('Hello World from console');
+print('Hello World from print');
+
+const ByteArray = imports.byteArray;
+
+const encoder = new TextEncoder();
+const encoded = encoder.encode('𝓽𝓮𝔁𝓽');
+
+// And so on...
+```
+
+### Ambient Modules
+
+You can import the built in [ambient modules](https://github.com/gjsify/ts-for-gir/tree/main/packages/cli#ambient-modules) of GJS.
+For this you need to include the `<%- npmScope %>/<%- importName %>` or `<%- npmScope %>/<%- importName %>/ambient` in your `tsconfig` or entry point Typescript file:
+    
+`index.ts`:
+```ts
+import '<%- npmScope %>/<%- importName %>'
+```
+
+`tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    ...
+  },
+  "include": ["<%- npmScope %>/<%- importName %>"],
+  ...
+}
+```
+
+Now you can import `gettext`, `system` and `cairo` in ESM style with Typescript support:
+
+```ts
+import gettext from 'gettext';
+import system from 'system';
+import cairo from 'cairo';
+```
+
+### GIR modules
+
+If you want to have types for [GObject Introspection](https://gi.readthedocs.io/en/latest/) modules, you have to add them to your dependencies and import them as well, see the description of these modules, e.g. [gtk-4.0](https://www.npmjs.com/package/@girs/gtk-4.0), [gio-2.0](https://www.npmjs.com/package/@girs/gio-2.0), [adw-1](https://www.npmjs.com/package/@girs/adw-1) and [much more](https://github.com/gjsify/types).
+
+These types will then be available to you:
+
+```ts
+import '@girs/gjs'
+import '@girs/gio-2.0'
+import '@girs/gtk-4.0'
+import '@girs/adw-1'
+
+import Gio from 'gi://Gio?version=2.0';
+import Gtk from 'gi://Gtk?version=4.0';
+import Adwaita from 'gi://adw?version=1';
+
+const button = new Gtk.Button();
+
+// ...
+
+```
+
+### Bundle
+
+Depending on your project configuration, it is recommended to use a bundler like [esbuild](https://esbuild.github.io/). You can find examples using different bundlers [here](https://github.com/gjsify/ts-for-gir/tree/main/examples).
+
+## Other packages
+
+All existing pre-generated packages can be found on [gjsify/types](https://github.com/gjsify/types).

package/templates/gjs/ambient.d.ts

@@ -0,0 +1,59 @@
+// https://www.typescriptlang.org/docs/handbook/modules.html#ambient-modules
+// https://stackoverflow.com/questions/45099605/ambient-declaration-with-an-imported-type-in-typescript
+
+declare module 'gettext' {
+  <%_ if(package){ _%>
+  export * from '@girs/gjs/gettext';
+  import Gettext from '@girs/gjs/gettext';
+  export default Gettext;
+  <%_ } else { _%>
+  const Gettext: typeof import('./gettext.js').default;
+  export default Gettext;
+
+  export const LocaleCategory: typeof import('./gettext.js').LocaleCategory;
+  export const setlocale: typeof import('./gettext.js').setlocale;
+  export const textdomain: typeof import('./gettext.js').textdomain;
+  export const bindtextdomain: typeof import('./gettext.js').bindtextdomain;
+  export const gettext: typeof import('./gettext.js').gettext;
+  export const dgettext: typeof import('./gettext.js').dgettext;
+  export const dcgettext: typeof import('./gettext.js').dcgettext;
+  export const ngettext: typeof import('./gettext.js').ngettext;
+  export const dngettext: typeof import('./gettext.js').dngettext;
+  export const pgettext: typeof import('./gettext.js').pgettext;
+  export const dpgettext: typeof import('./gettext.js').dpgettext;
+  export const domain: typeof import('./gettext.js').domain;
+  <%_ } _%>
+}
+
+declare module 'system' {
+  <%_ if(package){ _%>
+  export * from '@girs/gjs/system';
+  import System from '@girs/gjs/system';
+  export default System;
+  <%_ } else { _%>
+  const System: typeof import('./gettext.js').default;
+  export default System;
+
+  export const programInvocationName: typeof import('./system.js').programInvocationName;
+  export const version: typeof import('./system.js').version;
+  export const programPath: typeof import('./system.js').programPath;
+  export const programArgs: typeof import('./system.js').programArgs;
+  export const exit: typeof import('./system.js').exit;
+  export const addressOfGObject: typeof import('./system.js').addressOfGObject;
+  export const addressOf: typeof import('./system.js').addressOf;
+  export const gc: typeof import('./system.js').gc;
+  export const refcount: typeof import('./system.js').refcount;
+  export const dumpHeap: typeof import('./system.js').dumpHeap;
+  export const dumpMemoryInfo: typeof import('./system.js').dumpMemoryInfo;
+  <%_ } _%>
+}
+
+declare module 'cairo' {
+  <%_ if(package){ _%>
+  import Cairo from '@girs/gjs/cairo';
+  export default Cairo;
+  <%_ } else { _%>
+  const Cairo: typeof import('./cairo.js').default;
+  export default Cairo;
+  <%_ } _%>
+}

package/templates/gjs/cairo-1.0.d.ts

@@ -0,0 +1,9 @@
+// TODO
+// See
+// - https://gitlab.gnome.org/GNOME/gjs/-/blob/master/installed-tests/js/testCairoModule.js
+// - https://gitlab.gnome.org/GNOME/gjs/-/blob/master/installed-tests/js/testCairo.js
+// - https://gitlab.gnome.org/GNOME/gjs/-/blob/master/doc/cairo.md
+
+// image_surface_create -> ImageSurface
+// Context.constructor(surface: cairo.ImageSurface)
+// ...

package/templates/gjs/cairo.d.ts

@@ -0,0 +1,8 @@
+// TODO: See ./cairo-1.0.d.ts
+declare const Cairo: any;
+
+export default Cairo;
+
+<% if(moduleType === 'cjs') { %>
+  // TODO declare named exports here, cairo doesn't have named exports for its esm module but for cjs we can use `const { Context } = imports.cairo` for that, see `./cairo.js`
+<% } %>

package/templates/gjs/cairo.js

@@ -0,0 +1,11 @@
+<% if(moduleType === 'esm') { %>
+import Cairo from 'cairo';
+
+// cairo doesn't have named exports, see https://gitlab.gnome.org/GNOME/gjs/-/blob/c2a714f348d6848037f072063e0a914fd537c4f4/installed-tests/js/testCairoModule.js#L14
+export default Cairo;
+<% } else { %>
+const Cairo = imports.cairo;
+
+module.exports = Cairo;
+exports.default = Cairo;
+<% } %>

package/templates/gjs/gettext.d.ts

@@ -0,0 +1,41 @@
+export enum LocaleCategory {
+    ALL,
+    COLLATE,
+    CTYPE,
+    MESSAGES,
+    MONETARY,
+    NUMERIC,
+    TIME,
+}
+export function setlocale(category: number, locale: string | null): string
+export function textdomain(domainname: string | null): string
+export function bindtextdomain(domainname: string, dirname: string | null): string
+export function gettext(msgid: string): string
+export function dgettext(domainname: string | null, msgid: string): string
+export function dcgettext(domainname: string | null, msgid: string, category: number): string
+export function ngettext(msgid: string, msgid_plural: string, n: number): string
+export function dngettext(domainname: string, msgid: string, msgid_plural: string, n: number): string
+export function pgettext(context: string, msgid: string): string
+export function dpgettext(dom: string | null, context: string, msgid: string): string
+export function domain(domainName: string): {
+    gettext: (msgid: string) => string
+    ngettext: (msgid: string, msgid_plural: string, n: number) => string
+    pgettext: (context: string, msgid: string) => string
+}
+
+declare const Gettext: {
+    LocaleCategory: typeof LocaleCategory,
+    setlocale: typeof setlocale,
+    textdomain: typeof textdomain,
+    bindtextdomain: typeof bindtextdomain,
+    gettext: typeof gettext,
+    dgettext: typeof dgettext,
+    dcgettext: typeof dcgettext,
+    ngettext: typeof ngettext,
+    dngettext: typeof dngettext,
+    pgettext: typeof pgettext,
+    dpgettext: typeof dpgettext,
+    domain: typeof domain,
+}
+
+export default Gettext

package/templates/gjs/gettext.js

@@ -0,0 +1,11 @@
+<% if(moduleType === 'esm') { %>
+import Gettext, { setlocale, textdomain, bindtextdomain, gettext, dgettext, dcgettext, ngettext, dngettext, pgettext, dpgettext, domain } from 'gettext';
+
+export { setlocale, textdomain, bindtextdomain, gettext, dgettext, dcgettext, ngettext, dngettext, pgettext, dpgettext, domain }
+export default Gettext;
+<% } else { %>
+const Gettext = imports.gettext;
+
+module.exports = Gettext;
+exports.default = Gettext;
+<% } %>

package/templates/{Gjs/Gio-2.0.d.ts → gjs/gio-2.0.d.ts}

@@ -82,7 +82,7 @@ export class DBusExportedObject {
  * 
  * @example
  * ```js
- * import Gio from "gi://Gio";
+ * import Gio from "gi://Gio?version=2.0";
  * 
  * Gio._promisify(Gio.InputStream.prototype, 'read_bytes_async', 'read_bytes_finish');
  *