@gjsify/node-gi 0.13.0 → 0.20.0

package/gettext.js

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi/gettext — the GJS `Gettext` module on Node.
+//
+// GJS exposes a built-in `gettext` module (`import Gettext from 'gettext'` /
+// `imports.gettext`) — a convenience layer over GLib's gettext family. On Node
+// we provide a no-translation passthrough: every lookup returns the untranslated
+// msgid, which is exactly the correct fallback when no message catalog is bound
+// (GLib's gettext degrades to the same passthrough with no catalog). This keeps
+// GJS source that calls `Gettext.gettext(...)` at module load working unchanged
+// on Node without pulling in a real gettext binding.
+//
+// This is the single source of truth for the Gettext surface: the legacy
+// `imports.gettext` exposed by `@gjsify/node-gi/globals` re-uses this module's
+// default export. The gjsify `--app node` build aliases the bare `gettext`
+// specifier to this module (kept external — `ALIASES_GJS_FOR_NODE`).
+//
+// Reference: GJS's `gettext` module (refs/gjs/modules/esm/gettext.js +
+// modules/core/_gettext.js). Signatures mirror that surface.
+
+/** Look up `msgid` in the default domain. Passthrough — returns `msgid`. */
+export function gettext(msgid) {
+  return msgid;
+}
+
+/** Look up `msgid` in `domain`. Passthrough — returns `msgid`. */
+export function dgettext(_domain, msgid) {
+  return msgid;
+}
+
+/** Look up `msgid` in `domain`/`category`. Passthrough — returns `msgid`. */
+export function dcgettext(_domain, msgid, _category) {
+  return msgid;
+}
+
+/** Plural lookup in the default domain. Passthrough — singular for n===1, else plural. */
+export function ngettext(msgid1, msgid2, n) {
+  return n === 1 ? msgid1 : msgid2;
+}
+
+/** Plural lookup in `domain`. Passthrough — singular for n===1, else plural. */
+export function dngettext(_domain, msgid1, msgid2, n) {
+  return n === 1 ? msgid1 : msgid2;
+}
+
+/** Context lookup in the default domain. Passthrough — returns `msgid`. */
+export function pgettext(_context, msgid) {
+  return msgid;
+}
+
+/** Context lookup in `domain`. Passthrough — returns `msgid`. */
+export function dpgettext(_domain, _context, msgid) {
+  return msgid;
+}
+
+/**
+ * Create gettext bindings bound to a particular translation domain. Mirrors
+ * GJS's `Gettext.domain()` — returns an object with `gettext`/`ngettext`/
+ * `pgettext` bound to `domainName` (passthrough here).
+ */
+export function domain(_domainName) {
+  return {
+    gettext(msgid) {
+      return msgid;
+    },
+    ngettext(msgid1, msgid2, n) {
+      return n === 1 ? msgid1 : msgid2;
+    },
+    pgettext(_context, msgid) {
+      return msgid;
+    },
+  };
+}
+
+/** Set the locale for `category`. No-op on Node — returns null. */
+export function setlocale(_category, _locale) {
+  return null;
+}
+
+/** Set the default text domain. No-op on Node — returns null. */
+export function textdomain(_domainName) {
+  return null;
+}
+
+/** Bind a text domain to a directory. No-op on Node — returns null. */
+export function bindtextdomain(_domainName, _dirName) {
+  return null;
+}
+
+/** Set the output codeset for a text domain. No-op on Node — returns null. */
+export function bindtextdomainCodeset(_domainName, _codeset) {
+  return null;
+}
+
+/**
+ * The `LocaleCategory` enum — the standard POSIX locale category constants GJS
+ * surfaces via `GjsPrivate.LocaleCategory`.
+ */
+export const LocaleCategory = {
+  CTYPE: 0,
+  NUMERIC: 1,
+  TIME: 2,
+  COLLATE: 3,
+  MONETARY: 4,
+  MESSAGES: 5,
+  ALL: 6,
+};
+
+/**
+ * The GJS `Gettext` module as a default export — the object shape
+ * `import Gettext from 'gettext'` returns.
+ */
+const Gettext = {
+  gettext,
+  dgettext,
+  dcgettext,
+  ngettext,
+  dngettext,
+  pgettext,
+  dpgettext,
+  domain,
+  setlocale,
+  textdomain,
+  bindtextdomain,
+  bindtextdomainCodeset,
+  LocaleCategory,
+};
+
+export default Gettext;

package/gi.d.ts

@@ -10,12 +10,190 @@
 /** A GJS-shaped namespace object (members resolved dynamically). */
 export type GiNamespace = Record<string, unknown>;
 
+/**
+ * A plain descriptor produced by a `GObject.ParamSpec.*` factory and consumed by
+ * the {@link GObjectNamespace.registerClass} decorator (mapped to the native
+ * property spec). Not used directly.
+ */
+export interface ParamSpecDescriptor {
+  $paramSpec: true;
+  type: 'string' | 'boolean' | 'int' | 'uint' | 'int64' | 'uint64' | 'double' | 'float' | 'object' | 'boxed';
+  name: string;
+  nick?: string;
+  blurb?: string;
+  flags?: number;
+  default?: string | number | boolean;
+  minimum?: number;
+  maximum?: number;
+  /** For `object`/`boxed`: the value GType handle (resolved from a class ctor's `$gtype`). */
+  gtype?: unknown;
+}
+
+/** The `GObject.ParamSpec.*` factories surfaced on the GObject namespace. */
+export interface ParamSpecFactories {
+  string(name: string, nick: string, blurb: string, flags: number, defaultValue?: string): ParamSpecDescriptor;
+  boolean(name: string, nick: string, blurb: string, flags: number, defaultValue?: boolean): ParamSpecDescriptor;
+  int(name: string, nick: string, blurb: string, flags: number, minimum: number, maximum: number, defaultValue?: number): ParamSpecDescriptor;
+  uint(name: string, nick: string, blurb: string, flags: number, minimum: number, maximum: number, defaultValue?: number): ParamSpecDescriptor;
+  int64(name: string, nick: string, blurb: string, flags: number, minimum: number, maximum: number, defaultValue?: number): ParamSpecDescriptor;
+  uint64(name: string, nick: string, blurb: string, flags: number, minimum: number, maximum: number, defaultValue?: number): ParamSpecDescriptor;
+  double(name: string, nick: string, blurb: string, flags: number, minimum: number, maximum: number, defaultValue?: number): ParamSpecDescriptor;
+  float(name: string, nick: string, blurb: string, flags: number, minimum: number, maximum: number, defaultValue?: number): ParamSpecDescriptor;
+  /** A GObject-typed property; `gtype` is a class ctor (its `$gtype` is read) or a GType handle. */
+  object(name: string, nick: string, blurb: string, flags: number, gtype: unknown): ParamSpecDescriptor;
+  /** A boxed-typed property; `gtype` is a boxed class ctor (its `$gtype` is read) or a GType handle. */
+  boxed(name: string, nick: string, blurb: string, flags: number, gtype: unknown): ParamSpecDescriptor;
+}
+
+/** A `meta.Signals` entry for {@link GObjectNamespace.registerClass}. */
+export interface SignalDeclaration {
+  /** Parameter types in the node-gi vocabulary (e.g. `'int'`, `'string'`, `'object'`). */
+  param_types?: string[];
+  /** Return type (default `'void'`). */
+  return_type?: string;
+  /** `GSignalFlags` bitfield (default `RUN_LAST`). */
+  flags?: number;
+}
+
+/** The class-registration metadata accepted by {@link GObjectNamespace.registerClass}. */
+export interface RegisterClassMeta {
+  GTypeName?: string;
+  Properties?: Record<string, ParamSpecDescriptor>;
+  Signals?: Record<string, SignalDeclaration>;
+  /**
+   * A Gtk.Widget composite template: inline UI-XML (`Uint8Array`/Buffer or string)
+   * or a `"resource:///…"` path string. Installed on the subclass in `class_init`;
+   * `gtk_widget_init_template` runs at construction. (Gtk.Widget subclasses only.)
+   */
+  Template?: Uint8Array | string;
+  /** Template child ids exposed publicly on the instance as `this.<name>`. */
+  Children?: string[];
+  /** Template child ids exposed privately on the instance as `this._<name>`. */
+  InternalChildren?: string[];
+  /** `gtk_widget_class_set_css_name` for the subclass (Gtk.Widget subclasses only). */
+  CssName?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * The extra statics the `GObject` namespace carries on top of its introspected
+ * members (reached via `requireGi('GObject')`) — the GJS-shaped class-registration
+ * surface.
+ */
+export interface GObjectNamespace extends GiNamespace {
+  /**
+   * Register a GObject subclass declared as a JS class. Supports both
+   * `registerClass(class)` and `registerClass(meta, class)`. Returns a
+   * constructor whose `new`-ed instances are usable as GObjects (property get/set,
+   * `.connect/.emit/.disconnect`) and expose the user class's own prototype
+   * methods. `vfunc_<name>` prototype methods override the parent GObject vfuncs.
+   */
+  registerClass(klass: Function): Function;
+  registerClass(meta: RegisterClassMeta, klass: Function): Function;
+  ParamSpec: ParamSpecFactories;
+  /**
+   * The FULL introspected `GParamFlags` bitfield (READABLE/WRITABLE/READWRITE/
+   * CONSTRUCT/CONSTRUCT_ONLY/LAX_VALIDATION/STATIC_*/EXPLICIT_NOTIFY/DEPRECATED/
+   * …) — the named members below are the common convenience bits; the index
+   * signature covers the remaining introspected members.
+   */
+  ParamFlags: {
+    READABLE: number;
+    WRITABLE: number;
+    READWRITE: number;
+    CONSTRUCT: number;
+    CONSTRUCT_ONLY: number;
+    [member: string]: number;
+  };
+  /** The FULL introspected `GSignalFlags` bitfield (RUN_FIRST/RUN_LAST/RUN_CLEANUP/NO_RECURSE/DETAILED/ACTION/NO_HOOKS/MUST_COLLECT/DEPRECATED/…). */
+  SignalFlags: { RUN_FIRST: number; RUN_LAST: number; RUN_CLEANUP: number; [member: string]: number };
+  /**
+   * `GObject.Value` — `new GObject.Value()` / `new GObject.Value(gtype, value)`
+   * build a GValue; the boxed instance exposes `.init(gtype)`/`.set_*`/`.get_*`/
+   * `.copy`/`.unset`; static `type_compatible`/`type_transformable` route to the
+   * engine. `value instanceof GObject.Value` recognises a wrapped GValue.
+   */
+  Value: { new (): unknown; new (gtype: unknown, value: unknown): unknown; [staticMethod: string]: unknown };
+  /** gjs's fake enum for signal accumulators. */
+  AccumulatorType: { NONE: number; FIRST_WINS: number; TRUE_HANDLED: number };
+  /** Block every handler on `instance` connected with `fn`; returns the count matched. */
+  signal_handlers_block_by_func(instance: unknown, fn: Function): number;
+  /** Unblock every handler on `instance` connected with `fn`; returns the count matched. */
+  signal_handlers_unblock_by_func(instance: unknown, fn: Function): number;
+  /** Disconnect every handler on `instance` connected with `fn`; returns the count matched. */
+  signal_handlers_disconnect_by_func(instance: unknown, fn: Function): number;
+  /** Connect `handler` to `object`'s `name` signal via the instance's own `.connect`. */
+  signal_connect(object: unknown, name: string, handler: Function): number;
+  /** Connect `handler` in the after-phase via the instance's own `.connect_after`. */
+  signal_connect_after(object: unknown, name: string, handler: Function): number;
+  /** Emit `name` on `object` via the instance's own `.emit`. */
+  signal_emit_by_name(object: unknown, ...nameAndArgs: unknown[]): unknown;
+}
+
+/**
+ * A GJS-shaped GLib.Variant instance (reached via `new GLib.Variant(sig, value)`
+ * or returned/unpacked from the engine). Mirrors the GJS GLib.Variant override.
+ */
+export interface Variant {
+  /** Single-level unpack: container children stay {@link Variant}s. */
+  unpack(): unknown;
+  /**
+   * Deep unpack: container children are unpacked to JS, but a nested `v`
+   * (variant) value — e.g. an `a{sv}` value — STAYS a {@link Variant}.
+   */
+  deepUnpack(): unknown;
+  /** Backwards-compatible alias of {@link Variant.deepUnpack}. */
+  deep_unpack(): unknown;
+  /** Fully recursive unpack to plain JS (nested `v` variants are unwrapped). */
+  recursiveUnpack(): unknown;
+  /** The GVariant type string (e.g. `"a{sv}"`). */
+  get_type_string(): string;
+  toString(): string;
+  /** Other GVariant methods (n_children, get_child_value, print, …). */
+  [method: string]: unknown;
+}
+
+/**
+ * `GLib.Variant` as a class-like constructor surfaced on the GLib namespace.
+ * The deprecated `GLib.Variant.new(sig, value)` alias is reached via the static
+ * index signature.
+ */
+export interface VariantConstructor {
+  new (signature: string, value?: unknown): Variant;
+  [staticMethod: string]: unknown;
+}
+
+/**
+ * The extra statics the `GLib` namespace carries on top of its introspected
+ * members (reached via `requireGi('GLib')`) — the GJS-shaped `GLib.Variant`
+ * ergonomics replace the introspected struct-based Variant.
+ */
+export interface GLibNamespace extends GiNamespace {
+  Variant: VariantConstructor;
+  /**
+   * Pack `fields` (string / Uint8Array / {@link Variant} values) into an `a{sv}` and
+   * hand it to `g_log_variant` — gjs's `GLib.log_structured`.
+   */
+  log_structured(logDomain: string, logLevel: number, fields: Record<string, unknown>): void;
+  /** One-shot `idle_add` — the callback runs once, then the source is removed. */
+  idle_add_once(priority: number, callback: () => void): number;
+  /** One-shot `timeout_add` — the callback runs once, then the source is removed. */
+  timeout_add_once(priority: number, interval: number, callback: () => void): number;
+  /** One-shot `timeout_add_seconds` — the callback runs once, then the source is removed. */
+  timeout_add_seconds_once(priority: number, interval: number, callback: () => void): number;
+}
+
 /**
  * Require a GObject-Introspection namespace and return a GJS-shaped namespace
  * object. The Node twin of `import Ns from 'gi://Ns?version=X'` /
  * `imports.gi.Ns`. Members are resolved lazily from introspection: namespace
  * functions become callables, GObject types become constructors whose instances
  * expose `.method(...)`, `.prop` get/set and `.connect()/.emit()/.disconnect()`.
+ *
+ * The `GObject` namespace additionally carries the GJS runtime statics
+ * (`registerClass`, `ParamSpec`, `ParamFlags`, `SignalFlags`) — see
+ * {@link GObjectNamespace}. The `GLib` namespace carries the GJS-shaped
+ * `GLib.Variant` ergonomics — see {@link GLibNamespace}.
  */
 export function requireGi(namespace: string, version?: string): GiNamespace;