@gtkx/ffi 0.9.4 → 0.10.0

package/dist/native/error.d.ts

@@ -1,17 +1,31 @@
 /**
- * Error class that wraps a GLib GError.
- * Extends the native JavaScript Error with GError-specific properties.
+ * Error class wrapping GLib GError structures.
+ *
+ * Provides access to the error domain, code, and message from
+ * native GTK/GLib errors.
+ *
+ * @example
+ * ```tsx
+ * try {
+ *   file.loadContents();
+ * } catch (error) {
+ *   if (error instanceof NativeError) {
+ *     console.log(`GLib error ${error.domain}:${error.code}: ${error.message}`);
+ *   }
+ * }
+ * ```
  */
 export declare class NativeError extends Error {
-    /** The GError object id */
+    /** Native error pointer */
     readonly id: unknown;
-    /** The GLib error domain (GQuark) */
+    /** GLib error domain (quark) */
     readonly domain: number;
-    /** The error code within the domain */
+    /** Error code within the domain */
     readonly code: number;
     /**
-     * Creates a NativeError from a GError object id.
-     * @param id - The GError object id from a failed FFI call
+     * Creates a NativeError from a GError pointer.
+     *
+     * @param id - Native GError pointer
      */
     constructor(id: unknown);
 }

package/dist/native/error.js

@@ -1,18 +1,32 @@
 import { read } from "@gtkx/native";
 /**
- * Error class that wraps a GLib GError.
- * Extends the native JavaScript Error with GError-specific properties.
+ * Error class wrapping GLib GError structures.
+ *
+ * Provides access to the error domain, code, and message from
+ * native GTK/GLib errors.
+ *
+ * @example
+ * ```tsx
+ * try {
+ *   file.loadContents();
+ * } catch (error) {
+ *   if (error instanceof NativeError) {
+ *     console.log(`GLib error ${error.domain}:${error.code}: ${error.message}`);
+ *   }
+ * }
+ * ```
  */
 export class NativeError extends Error {
-    /** The GError object id */
+    /** Native error pointer */
     id;
-    /** The GLib error domain (GQuark) */
+    /** GLib error domain (quark) */
     domain;
-    /** The error code within the domain */
+    /** Error code within the domain */
     code;
     /**
-     * Creates a NativeError from a GError object id.
-     * @param id - The GError object id from a failed FFI call
+     * Creates a NativeError from a GError pointer.
+     *
+     * @param id - Native GError pointer
      */
     constructor(id) {
         const message = read(id, { type: "string" }, 8);

package/dist/native/events.d.ts

@@ -1,11 +1,31 @@
 import EventEmitter from "node:events";
+/**
+ * Event map for application lifecycle events.
+ */
 type NativeEventMap = {
+    /** Emitted when the GTK application starts */
     start: [];
+    /** Emitted when the GTK application stops */
     stop: [];
 };
 /**
- * Event emitter for GTK lifecycle events.
- * Emits "start" when GTK is initialized and "stop" before shutdown.
+ * Event emitter for GTK application lifecycle events.
+ *
+ * Emits "start" when {@link start} is called and "stop" when
+ * {@link stop} is called.
+ *
+ * @example
+ * ```tsx
+ * import { events } from "@gtkx/ffi";
+ *
+ * events.on("start", () => {
+ *   console.log("Application started");
+ * });
+ *
+ * events.on("stop", () => {
+ *   console.log("Application stopping");
+ * });
+ * ```
  */
 export declare const events: EventEmitter<NativeEventMap>;
 export {};

package/dist/native/events.js

@@ -1,6 +1,21 @@
 import EventEmitter from "node:events";
 /**
- * Event emitter for GTK lifecycle events.
- * Emits "start" when GTK is initialized and "stop" before shutdown.
+ * Event emitter for GTK application lifecycle events.
+ *
+ * Emits "start" when {@link start} is called and "stop" when
+ * {@link stop} is called.
+ *
+ * @example
+ * ```tsx
+ * import { events } from "@gtkx/ffi";
+ *
+ * events.on("start", () => {
+ *   console.log("Application started");
+ * });
+ *
+ * events.on("stop", () => {
+ *   console.log("Application stopping");
+ * });
+ * ```
  */
 export const events = new EventEmitter();

package/dist/native/lifecycle.d.ts

@@ -1,23 +1,32 @@
 import type { ApplicationFlags } from "../generated/gio/enums.js";
-import { Application } from "../generated/gtk/application.js";
+import type { Application } from "../generated/gtk/application.js";
 /**
- * Gets the current GTK application instance.
- * @returns The GTK Application instance
- * @throws Error if GTK has not been started yet
- */
-export declare const getApplication: () => Application;
-/**
- * Starts the GTK application with the given application ID.
- * Sets up a keep-alive timer to prevent Node.js from exiting.
- * This function is idempotent - calling it multiple times returns the existing app.
- * @param appId - The application ID (e.g., "com.example.myapp")
+ * Initializes the GTK application runtime.
+ *
+ * Creates a GTK Application instance, initializes Adwaita and GtkSource
+ * if available, and starts the event loop.
+ *
+ * @param appId - Application ID in reverse domain notation (e.g., "com.example.app")
  * @param flags - Optional GIO application flags
  * @returns The GTK Application instance
+ *
+ * @example
+ * ```tsx
+ * import { start } from "@gtkx/ffi";
+ *
+ * const app = start("com.example.myapp");
+ * ```
+ *
+ * @see {@link stop} for shutting down the application
  */
 export declare const start: (appId: string, flags?: ApplicationFlags) => Application;
 /**
- * Stops the GTK application and cleans up the keep-alive timer.
- * Emits the "stop" event before shutting down to allow cleanup.
- * This function is idempotent - calling it when not started does nothing.
+ * Shuts down the GTK application runtime.
+ *
+ * Stops the event loop, cleans up resources, and finalizes libraries.
+ * Emits a "stop" event before cleanup.
+ *
+ * @see {@link start} for initializing the application
+ * @see {@link events} for lifecycle event handling
  */
 export declare const stop: () => void;

package/dist/native/lifecycle.js

@@ -1,13 +1,12 @@
 import { poll as nativePoll, start as nativeStart, stop as nativeStop } from "@gtkx/native";
 import { init as initAdwaita } from "../generated/adw/functions.js";
-import { Application } from "../generated/gtk/application.js";
 import { finalize as finalizeGtkSource, init as initGtkSource } from "../generated/gtksource/functions.js";
 import { events } from "./events.js";
 import { getNativeObject } from "./object.js";
 const isDeno = typeof Deno !== "undefined";
-let currentApp = null;
 let keepAliveTimeout = null;
 let pollInterval = null;
+let application = null;
 const keepAlive = () => {
     keepAliveTimeout = setTimeout(() => keepAlive(), 2147483647);
 };
@@ -23,30 +22,29 @@ const stopPolling = () => {
     }
 };
 /**
- * Gets the current GTK application instance.
- * @returns The GTK Application instance
- * @throws Error if GTK has not been started yet
- */
-export const getApplication = () => {
-    if (!currentApp) {
-        throw new Error("GTK application not initialized. Call start() first.");
-    }
-    return currentApp;
-};
-/**
- * Starts the GTK application with the given application ID.
- * Sets up a keep-alive timer to prevent Node.js from exiting.
- * This function is idempotent - calling it multiple times returns the existing app.
- * @param appId - The application ID (e.g., "com.example.myapp")
+ * Initializes the GTK application runtime.
+ *
+ * Creates a GTK Application instance, initializes Adwaita and GtkSource
+ * if available, and starts the event loop.
+ *
+ * @param appId - Application ID in reverse domain notation (e.g., "com.example.app")
  * @param flags - Optional GIO application flags
  * @returns The GTK Application instance
+ *
+ * @example
+ * ```tsx
+ * import { start } from "@gtkx/ffi";
+ *
+ * const app = start("com.example.myapp");
+ * ```
+ *
+ * @see {@link stop} for shutting down the application
  */
 export const start = (appId, flags) => {
-    if (currentApp) {
-        return currentApp;
+    if (application) {
+        return application;
     }
     const app = nativeStart(appId, flags);
-    currentApp = getNativeObject(app, Application);
     events.emit("start");
     try {
         initAdwaita();
@@ -57,18 +55,20 @@ export const start = (appId, flags) => {
     if (isDeno) {
         startPolling();
     }
-    if (!currentApp) {
-        throw new Error("Failed to initialize GTK Application.");
-    }
-    return currentApp;
+    application = getNativeObject(app);
+    return application;
 };
 /**
- * Stops the GTK application and cleans up the keep-alive timer.
- * Emits the "stop" event before shutting down to allow cleanup.
- * This function is idempotent - calling it when not started does nothing.
+ * Shuts down the GTK application runtime.
+ *
+ * Stops the event loop, cleans up resources, and finalizes libraries.
+ * Emits a "stop" event before cleanup.
+ *
+ * @see {@link start} for initializing the application
+ * @see {@link events} for lifecycle event handling
  */
 export const stop = () => {
-    if (!currentApp) {
+    if (!application) {
         return;
     }
     if (keepAliveTimeout) {
@@ -81,6 +81,6 @@ export const stop = () => {
         finalizeGtkSource();
     }
     catch { }
+    application = null;
     nativeStop();
-    currentApp = null;
 };

package/dist/native/object.d.ts

@@ -1,18 +1,23 @@
 import type { NativeClass, NativeObject } from "./base.js";
 /**
- * Wraps a native object id in a class instance without calling the constructor.
+ * Creates a typed JavaScript wrapper for a native GTK object.
  *
- * When called without a targetType, uses GLib's type system to determine the
- * actual runtime type and wraps with the correct class prototype.
+ * Wraps a native object pointer in a JavaScript class instance,
+ * providing type-safe access to GTK methods and properties.
  *
- * When called with a targetType:
- * - For interfaces: checks if the object implements the interface, returns null if not
- * - For boxed types and GObjects: creates an instance with the target prototype
+ * @typeParam T - The expected wrapper class type
+ * @param id - Native object pointer/ID
+ * @param targetType - Optional target class for interface type checking
+ * @returns The typed wrapper instance, or null if the input is null/undefined
  *
- * @param id - The native object id to wrap
- * @param targetType - Optional target type class
- * @returns A new instance with the id attached, or null for failed interface checks
- * @throws Error if no registered class is found (when no targetType provided)
+ * @example
+ * ```tsx
+ * import { getNativeObject } from "@gtkx/ffi";
+ * import * as Gtk from "@gtkx/ffi/gtk";
+ *
+ * const widget = getNativeObject(nativeId, Gtk.Widget);
+ * widget?.setVisible(true);
+ * ```
  */
 export declare function getNativeObject<T extends NativeObject = NativeObject>(id: unknown, targetType?: NativeClass<T>): T | null;
 export { isInstantiating, type NativeClass, NativeObject, setInstantiating } from "./base.js";

package/dist/native/object.js

@@ -2,19 +2,24 @@ import { getObjectId } from "@gtkx/native";
 import { typeCheckInstanceIsA, typeFromName, typeNameFromInstance } from "../generated/gobject/functions.js";
 import { findNativeClass } from "../registry.js";
 /**
- * Wraps a native object id in a class instance without calling the constructor.
+ * Creates a typed JavaScript wrapper for a native GTK object.
  *
- * When called without a targetType, uses GLib's type system to determine the
- * actual runtime type and wraps with the correct class prototype.
+ * Wraps a native object pointer in a JavaScript class instance,
+ * providing type-safe access to GTK methods and properties.
  *
- * When called with a targetType:
- * - For interfaces: checks if the object implements the interface, returns null if not
- * - For boxed types and GObjects: creates an instance with the target prototype
+ * @typeParam T - The expected wrapper class type
+ * @param id - Native object pointer/ID
+ * @param targetType - Optional target class for interface type checking
+ * @returns The typed wrapper instance, or null if the input is null/undefined
  *
- * @param id - The native object id to wrap
- * @param targetType - Optional target type class
- * @returns A new instance with the id attached, or null for failed interface checks
- * @throws Error if no registered class is found (when no targetType provided)
+ * @example
+ * ```tsx
+ * import { getNativeObject } from "@gtkx/ffi";
+ * import * as Gtk from "@gtkx/ffi/gtk";
+ *
+ * const widget = getNativeObject(nativeId, Gtk.Widget);
+ * widget?.setVisible(true);
+ * ```
  */
 export function getNativeObject(id, targetType) {
     if (id === null || id === undefined) {
@@ -37,7 +42,7 @@ export function getNativeObject(id, targetType) {
     const runtimeTypeName = typeNameFromInstance(objectId);
     const cls = findNativeClass(runtimeTypeName);
     if (!cls) {
-        throw new Error(`Unknown GLib type: ${runtimeTypeName}. Make sure the class is registered.`);
+        throw new Error(`Expected registered GLib type, got '${runtimeTypeName}'`);
     }
     const instance = Object.create(cls.prototype);
     instance.id = id;

package/dist/registry.d.ts

@@ -1,19 +1,38 @@
 import type { NativeClass } from "./native/object.js";
 /**
- * Registers a class in the global GObject type registry.
- * Called by generated code at module load time.
- * @param cls - The class to register
+ * Registers a native class for type resolution.
+ *
+ * Called automatically by generated bindings. Can be used to register
+ * custom subclasses.
+ *
+ * @param cls - The native class to register
+ *
+ * @example
+ * ```tsx
+ * import { registerNativeClass } from "@gtkx/ffi";
+ *
+ * class MyCustomWidget extends Gtk.Widget {
+ *   static readonly glibTypeName = "MyCustomWidget";
+ *   // ...
+ * }
+ * registerNativeClass(MyCustomWidget);
+ * ```
  */
 export declare function registerNativeClass(cls: NativeClass): void;
 /**
- * Looks up a class by its GLib type name.
+ * Gets a registered class by its GLib type name.
+ *
  * @param glibTypeName - The GLib type name (e.g., "GtkButton")
- * @returns The class constructor, or undefined if not found
+ * @returns The registered class, or undefined if not found
  */
 export declare function getNativeClass(glibTypeName: string): NativeClass | undefined;
 /**
- * Finds the nearest registered class by walking up the type hierarchy.
+ * Finds a native class by walking the type hierarchy.
+ *
+ * If the exact type is not registered, walks up the parent chain
+ * until a registered type is found.
+ *
  * @param glibTypeName - The GLib type name to start from
- * @returns The registered class, or undefined if none found
+ * @returns The closest registered parent class, or undefined
  */
 export declare const findNativeClass: (glibTypeName: string) => NativeClass | undefined;

package/dist/registry.js

@@ -1,25 +1,44 @@
 import { typeFromName, typeName, typeParent } from "./generated/gobject/functions.js";
 const registry = new Map();
 /**
- * Registers a class in the global GObject type registry.
- * Called by generated code at module load time.
- * @param cls - The class to register
+ * Registers a native class for type resolution.
+ *
+ * Called automatically by generated bindings. Can be used to register
+ * custom subclasses.
+ *
+ * @param cls - The native class to register
+ *
+ * @example
+ * ```tsx
+ * import { registerNativeClass } from "@gtkx/ffi";
+ *
+ * class MyCustomWidget extends Gtk.Widget {
+ *   static readonly glibTypeName = "MyCustomWidget";
+ *   // ...
+ * }
+ * registerNativeClass(MyCustomWidget);
+ * ```
  */
 export function registerNativeClass(cls) {
     registry.set(cls.glibTypeName, cls);
 }
 /**
- * Looks up a class by its GLib type name.
+ * Gets a registered class by its GLib type name.
+ *
  * @param glibTypeName - The GLib type name (e.g., "GtkButton")
- * @returns The class constructor, or undefined if not found
+ * @returns The registered class, or undefined if not found
  */
 export function getNativeClass(glibTypeName) {
     return registry.get(glibTypeName);
 }
 /**
- * Finds the nearest registered class by walking up the type hierarchy.
+ * Finds a native class by walking the type hierarchy.
+ *
+ * If the exact type is not registered, walks up the parent chain
+ * until a registered type is found.
+ *
  * @param glibTypeName - The GLib type name to start from
- * @returns The registered class, or undefined if none found
+ * @returns The closest registered parent class, or undefined
  */
 export const findNativeClass = (glibTypeName) => {
     let currentTypeName = glibTypeName;
@@ -35,5 +54,4 @@ export const findNativeClass = (glibTypeName) => {
             break;
         currentTypeName = typeName(parentGtype);
     }
-    return undefined;
 };

package/dist/types.d.ts

@@ -1,4 +1,5 @@
+import type { Type } from "@gtkx/native";
 export type SignalMeta = Record<string, {
-    params: import("@gtkx/native").Type[];
-    returnType?: import("@gtkx/native").Type;
+    params: Type[];
+    returnType?: Type;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/ffi",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Generated TypeScript FFI bindings for GTK4 libraries",
   "keywords": [
     "gtk",
@@ -46,14 +46,14 @@
     "dist"
   ],
   "dependencies": {
-    "@gtkx/native": "0.9.4"
+    "@gtkx/native": "0.10.0"
   },
   "devDependencies": {
-    "@gtkx/gir": "0.9.4"
+    "@gtkx/codegen": "0.0.0"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",
-    "codegen": "tsx scripts/codegen.ts",
+    "codegen": "gtkx-codegen ffi --girs-dir ../../girs --output-dir src/generated",
     "test": "../../scripts/run-tests.sh"
   }
 }

package/dist/codegen/ffi-generator.d.ts

@@ -1,109 +0,0 @@
-import type { GirNamespace, TypeRegistry } from "@gtkx/gir";
-type GeneratorOptions = {
-    outputDir: string;
-    namespace: string;
-    prettierConfig?: unknown;
-    typeRegistry?: TypeRegistry;
-    allNamespaces?: Map<string, GirNamespace>;
-};
-export declare class CodeGenerator {
-    private options;
-    private typeMapper;
-    private usesRef;
-    private usesCall;
-    private usesInstantiating;
-    private addGioImport;
-    private usesType;
-    private usesRead;
-    private usesWrite;
-    private usesAlloc;
-    private usesNativeError;
-    private usesNativeObject;
-    private usesGetNativeObject;
-    private usesRegisterNativeClass;
-    private usesGetClassByTypeName;
-    private usesSignalMeta;
-    private usedEnums;
-    private usedRecords;
-    private usedExternalTypes;
-    private usedSameNamespaceClasses;
-    private usedInterfaces;
-    private signalClasses;
-    private recordNameToFile;
-    private interfaceNameToFile;
-    private currentSharedLibrary;
-    private cyclicReturnTypes;
-    private methodRenames;
-    constructor(options: GeneratorOptions);
-    private sanitizeDoc;
-    private formatDoc;
-    private formatMethodDoc;
-    generateNamespace(namespace: GirNamespace): Promise<Map<string, string>>;
-    private registerEnumsAndBitfields;
-    private registerRecords;
-    private shouldGenerateRecord;
-    private buildClassMap;
-    private registerInterfaces;
-    private buildInterfaceMap;
-    private getStandaloneFunctions;
-    private resetState;
-    private generateClass;
-    private topologicalSortClasses;
-    private isDescendantOf;
-    private computeCyclicReturnTypes;
-    private wouldCreateCycle;
-    private getAncestors;
-    private classImports;
-    private collectParentMethodNames;
-    private collectAllSignals;
-    private generateConstructors;
-    private generateConstructorWithFlag;
-    private generateGObjectNewConstructorWithFlag;
-    private generateStaticFactoryMethod;
-    private generateStaticFunctions;
-    private generateStaticFunction;
-    private generateMethods;
-    private hasAsyncCallback;
-    private findFinishMethod;
-    private generateAsyncWrapper;
-    private buildAsyncReturnType;
-    private buildAsyncCallArgs;
-    private generateFinishCallArguments;
-    private generateMethod;
-    private extractSignalParamClass;
-    private generateSignalConnect;
-    private generateInterface;
-    private generateRecord;
-    private generateRecordInitInterface;
-    private generateRecordConstructors;
-    private generateRecordFromPtr;
-    private getWritableFields;
-    private generateFieldInitInterface;
-    private generateRecordCreatePtr;
-    private generateFieldWrites;
-    private calculateStructSize;
-    private generateRecordStaticFactoryMethod;
-    private generateRecordStaticFunctions;
-    private generateRecordMethods;
-    private generateRecordFields;
-    private isWritableType;
-    private getFieldSize;
-    private getFieldAlignment;
-    private generateFunctions;
-    private generateFunction;
-    private generateEnums;
-    private generateConstants;
-    private generateIndex;
-    private generateParameterList;
-    private generateCallArguments;
-    private identifyGtkAllocatesRefs;
-    private generateRefRewrapCode;
-    private generateErrorArgument;
-    private generateErrorCheck;
-    private generateTypeDescriptor;
-    private generateImports;
-    private formatCode;
-    private generateCyclicTypeReturn;
-    private addSignalCatchAllOverload;
-}
-export {};