node-gtk 0.14.0 → 2.0.0

package/src/value.h

@@ -11,23 +11,45 @@ using v8::Local;
 
 namespace GNodeJS {
 
+enum ResourceOwnership {
+    kNone,
+    kCopy,
+    kTransfer
+};
+
 Local<Value> GListToV8  (GITypeInfo *info, GList  *glist);
 Local<Value> GSListToV8 (GITypeInfo *info, GSList *glist);
 Local<Value> GHashToV8 (GITypeInfo *info, GHashTable *hash);
 Local<Value> ArrayToV8  (GITypeInfo *info, gpointer data, long length = -1);
-Local<Value> GErrorToV8 (GITypeInfo *type_info, GError *err);
-Local<Value> GIArgumentToV8 (GITypeInfo *type_info, GIArgument *argument, long length = -1, bool mustCopy = false);
+Local<Value> GErrorToV8 (GITypeInfo *type_info, GError *err, ResourceOwnership ownership = kNone);
+Local<Value> GIArgumentToV8 (GITypeInfo *type_info, GIArgument *argument, long length = -1, ResourceOwnership ownership = kNone);
 long         GIArgumentToLength(GITypeInfo *type_info, GIArgument *arg, bool is_pointer);
 
-bool         V8ToGIArgument (GITypeInfo *type_info, GIArgument *argument, Local<Value> value);
+bool         V8ToGIArgumentInterface (GIBaseInfo *gi_info, GIArgument *argument, Local<Value> value);
 bool         V8ToGIArgument (GITypeInfo *type_info, GIArgument *argument, Local<Value> value, bool may_be_null);
 bool         V8ToOutGIArgument(GITypeInfo *type_info, GIArgument *arg, Local<Value> value, bool may_be_null);
 void         FreeGIArgument (GITypeInfo *type_info, GIArgument *argument, GITransfer transfer = GI_TRANSFER_EVERYTHING, GIDirection direction = GI_DIRECTION_OUT);
 void         FreeGIArgumentArray (GITypeInfo *type_info, GIArgument *arg, GITransfer transfer = GI_TRANSFER_EVERYTHING, GIDirection direction = GI_DIRECTION_OUT, long length = -1);
+
+// For a transfer-container IN GList/GSList/GHashTable, the callee frees the
+// container structure itself, so node-gtk cannot walk it afterwards to free
+// the (caller-owned) elements. These capture the element pointers *before*
+// the call so they can be freed *after* it. See #399.
+bool         IsTransferContainerInList (GITypeInfo *type_info, GITransfer transfer, GIDirection direction);
+gpointer     CaptureTransferContainerElements (GITypeInfo *type_info, gpointer container);
+void         FreeTransferContainerElements (GITypeInfo *type_info, gpointer captured);
+
+// For a transfer-full IN boxed argument (or a C array of boxed pointers) the
+// callee frees the passed memory, but the JS wrapper still owns its own copy,
+// which would then be double-freed when the wrapper is finalized. Replace each
+// such pointer with a g_boxed_copy so only the copy is handed to the callee.
+// See #409.
+void         CopyBoxedForTransferFullIn (GITypeInfo *type_info, GIArgument *arg, long length);
+
 bool         CanConvertV8ToGIArgument (GITypeInfo *type_info, Local<Value> value, bool may_be_null);
 
-bool         V8ToGValue(GValue *gvalue, Local<Value> value, bool mustCopy = false);
-Local<Value> GValueToV8(const GValue *gvalue, bool mustCopy = false);
+bool         V8ToGValue(GValue *gvalue, Local<Value> value, ResourceOwnership ownership = kNone);
+Local<Value> GValueToV8(const GValue *gvalue, ResourceOwnership ownership = kNone);
 bool         CanConvertV8ToGValue(GValue *gvalue, Local<Value> value);
 
 bool         ValueHasInternalField  (Local<Value> value);

package/tools/README.md

@@ -0,0 +1,91 @@
+# node-gtk TypeScript types — PROTOTYPE (Model B: generate-on-demand)
+
+Types are generated **on the user's machine** from the GObject-Introspection
+typelibs they actually have installed, using node-gtk's own runtime introspection
+(`require('node-gtk')._GIRepository`, the libgirepository C API exposed to JS).
+Because the generator reads the same typelibs and applies the same name/shape
+rules as `lib/bootstrap.js`, the output matches what node-gtk produces at runtime
+— and it matches *their* library versions, not a bundled snapshot.
+
+## User workflow
+
+```sh
+# 1. generate types for the namespaces you use (+ their dependency closure).
+#    Output defaults to ./node_modules/.node-gtk-types (hidden, gitignored).
+npx node-gtk generate-types Gtk-4.0
+
+# 2. point tsconfig at the generated shim
+```
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "paths": { "node-gtk": ["./node_modules/.node-gtk-types/node-gtk.d.ts"] }
+  }
+}
+```
+```ts
+// 3. write code — gi.require() is typed by string-literal overloads
+import * as gi from 'node-gtk'
+const Gtk = gi.require('Gtk', '4.0')      // inferred as the Gtk-4.0 namespace
+const win = new Gtk.ApplicationWindow({ title: 'Hi', defaultWidth: 400 })
+win.on('close-request', () => false)
+```
+
+`generate-types` emits one `<Namespace>-<version>.d.ts` per namespace plus a
+`node-gtk.d.ts` module shim. The shim overloads `require()` so each
+`gi.require('Ns','ver')` resolves to the matching generated namespace; namespaces
+you didn't generate fall back to `any`. Because the default output lives under
+`node_modules`, it's treated as a generated cache — wire it into a `postinstall`
+script so it regenerates after install.
+
+## Pieces (prototype)
+
+- `bin/node-gtk.js` — CLI entry (`package.json` `"bin"`); dispatches `generate-types`.
+- `tools/generate-types.js` — the generator. `run(argv)` / `generate(roots, outdir)`.
+- `examples/ts-demo/` — `app.ts` (valid, typechecks clean) and `app-errors.ts`
+  (4 deliberate mistakes, all caught). Generate types into `.node-gtk-types/` first
+  (see that dir's `.gitignore`).
+
+## Verify the demo
+
+```sh
+node bin/node-gtk.js generate-types Gtk-4.0 --outdir examples/ts-demo/.node-gtk-types
+node_modules/.bin/tsc -p examples/ts-demo/tsconfig.json          # passes clean
+sed 's/app.ts/app-errors.ts/' examples/ts-demo/tsconfig.json > examples/ts-demo/tsconfig.errors.json
+node_modules/.bin/tsc -p examples/ts-demo/tsconfig.errors.json   # 4 errors caught
+```
+
+## Fidelity
+
+The generated `.d.ts` for the full Gtk-3.0, Gtk-4.0, and Adw/GtkSource stacks
+type-check with **0 errors even without `skipLibCheck`**. Modelled faithfully:
+
+- OUT/INOUT params surfaced via the return value as node-gtk does
+  (`getStartIter(): TextIter`, `getIterAtLine(n): [boolean, TextIter]`).
+- Callback argument types expanded (e.g. `Gio.AsyncReadyCallback`).
+- 64-bit ints return `bigint` (full precision, #323/#149); params accept
+  `number | bigint`.
+- Enum methods and interface constants emitted (declaration-merged).
+- GObject override conflicts reconciled as overloads, so subclass methods stay
+  assignable to inherited ones; multiple-interface signal/method conflicts
+  resolved with a unified, assignable-to-all declaration.
+- Interfaces emit both a type and a value, so constructor functions and
+  constants work (`Gio.File.newForPath(...)`).
+- Relative imports use `.js` extensions, so the output works under
+  `moduleResolution` node16/nodenext (and bundler). `skipLibCheck` is no longer
+  required for the GTK stack, though it remains a fine default.
+- **JSDoc comments** from the `.gir` XML — class/method/property/signal/enum
+  docs, with `@param`/`@returns`/`@deprecated` — so editors show GNOME's API docs
+  on hover. The typelib doesn't carry docs, so this reads the matching
+  `<Namespace>-<version>.gir` from `$XDG_DATA_DIRS/gir-1.0` (shipped by the
+  library's `-dev`/`-devel` package). Best-effort: if the `.gir` is absent, types
+  still generate without comments. Pass `--no-docs` for leaner output (~5× smaller).
+
+## Remaining limitations
+
+- **Overriding an inherited method that collides by name** in a user subclass
+  (e.g. a gutter renderer's `activate(iter, …)` vs `GtkWidget.activate()`)
+  requires the override to satisfy both signatures — an inherent consequence of
+  the GObject API reusing a name, not specific to these types.