react-presenter 0.1.0

package/dist/index.cjs

@@ -0,0 +1,268 @@
+'use strict';
+
+// src/proxy.ts
+var memoCache = /* @__PURE__ */ new WeakMap();
+function createDataProxy(presenter, data, options = {}) {
+  return new Proxy(presenter, {
+    get(target, property, receiver) {
+      if (property in target) {
+        if (options.memoize && typeof property === "string") {
+          const proto = Object.getPrototypeOf(target);
+          const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, property) : void 0;
+          if (descriptor && typeof descriptor.get === "function") {
+            let cache = memoCache.get(target);
+            if (!cache) {
+              cache = /* @__PURE__ */ new Map();
+              memoCache.set(target, cache);
+            }
+            if (cache.has(property)) {
+              return cache.get(property);
+            }
+            const value = Reflect.get(target, property, receiver);
+            cache.set(property, value);
+            return value;
+          }
+        }
+        return Reflect.get(target, property, receiver);
+      }
+      if (typeof property === "string" && data !== null && typeof data === "object" && property in data) {
+        return data[property];
+      }
+      return void 0;
+    },
+    has(target, property) {
+      if (property in target) return true;
+      if (data !== null && typeof data === "object") {
+        return property in data;
+      }
+      return false;
+    }
+  });
+}
+
+// src/reflection.ts
+var EXCLUDED_KEYS = /* @__PURE__ */ new Set(["constructor"]);
+function getGetterNames(instance, stopAt) {
+  const names = /* @__PURE__ */ new Set();
+  let proto = Object.getPrototypeOf(instance);
+  while (proto && proto !== Object.prototype) {
+    if (proto === stopAt.prototype) break;
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {
+      if (!EXCLUDED_KEYS.has(key) && typeof descriptor.get === "function") {
+        names.add(key);
+      }
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return Array.from(names);
+}
+function getAsyncMethodNames(instance, stopAt) {
+  const names = /* @__PURE__ */ new Set();
+  let proto = Object.getPrototypeOf(instance);
+  while (proto && proto !== Object.prototype) {
+    if (proto === stopAt.prototype) break;
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {
+      if (!EXCLUDED_KEYS.has(key) && typeof descriptor.value === "function" && descriptor.value.constructor?.name === "AsyncFunction") {
+        names.add(key);
+      }
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return Array.from(names);
+}
+
+// src/serialize.ts
+function serializePresenter(presenter, stopAt, options = {}) {
+  const allKeys = getGetterNames(presenter, stopAt);
+  const onlySet = options.only ? new Set(options.only) : null;
+  const exceptSet = options.except ? new Set(options.except) : null;
+  const allowedKeys = allKeys.filter((key) => {
+    if (onlySet && !onlySet.has(key)) return false;
+    if (exceptSet && exceptSet.has(key)) return false;
+    return true;
+  });
+  const orderedKeys = onlySet ? Array.from(onlySet).filter((key) => allowedKeys.includes(key)) : allowedKeys;
+  const result = {};
+  for (const key of orderedKeys) {
+    try {
+      result[key] = presenter[key];
+    } catch {
+      result[key] = void 0;
+    }
+  }
+  return result;
+}
+
+// src/config.ts
+var globalConfig = {
+  locale: "en-US"
+};
+function configurePresenter(config) {
+  globalConfig = { ...globalConfig, ...config };
+}
+function getPresenterConfig() {
+  return globalConfig;
+}
+var defaultTranslate = (key) => key;
+
+// src/format.ts
+function toDate(value) {
+  return value instanceof Date ? value : new Date(value);
+}
+var RELATIVE_DIVISORS_MS = {
+  year: 1e3 * 60 * 60 * 24 * 365,
+  quarter: 1e3 * 60 * 60 * 24 * 91,
+  month: 1e3 * 60 * 60 * 24 * 30,
+  week: 1e3 * 60 * 60 * 24 * 7,
+  day: 1e3 * 60 * 60 * 24,
+  hour: 1e3 * 60 * 60,
+  minute: 1e3 * 60,
+  second: 1e3
+};
+function createFormatAdapter(locale) {
+  const config = getPresenterConfig();
+  const resolvedLocale = locale ?? config.locale ?? "en-US";
+  const overrides = config.formatters ?? {};
+  const base = {
+    date(value, options) {
+      return new Intl.DateTimeFormat(resolvedLocale, options).format(toDate(value));
+    },
+    number(value, options) {
+      return new Intl.NumberFormat(resolvedLocale, options).format(value);
+    },
+    currency(value, currency = "USD", options) {
+      return new Intl.NumberFormat(resolvedLocale, {
+        style: "currency",
+        currency,
+        ...options
+      }).format(value);
+    },
+    relativeTime(value, unit = "day") {
+      const date = toDate(value);
+      const diffMs = date.getTime() - Date.now();
+      const divisor = RELATIVE_DIVISORS_MS[unit] ?? RELATIVE_DIVISORS_MS.day;
+      const rtf = new Intl.RelativeTimeFormat(resolvedLocale, { numeric: "auto" });
+      return rtf.format(Math.round(diffMs / divisor), unit);
+    }
+  };
+  return { ...base, ...overrides };
+}
+
+// src/Presenter.ts
+var Presenter = class _Presenter {
+  constructor(data, context) {
+    this.data = data;
+    this.context = context ?? {};
+  }
+  /**
+   * Intl-backed date/number/currency/relative-time formatting, aware of
+   * `context.locale`. Override globally via `configurePresenter`.
+   */
+  get format() {
+    const locale = this.context?.locale;
+    return createFormatAdapter(locale);
+  }
+  /**
+   * Translate a key via the globally configured `translate` function
+   * (wire up i18next / next-intl / FormatJS / etc. once with
+   * `configurePresenter({ translate })`). Falls back to returning the key
+   * itself if nothing is configured, so it's always safe to call.
+   */
+  t(key, params) {
+    const config = getPresenterConfig();
+    const translate = config.translate ?? defaultTranslate;
+    const locale = this.context?.locale;
+    return translate(key, params, locale ?? config.locale);
+  }
+  /**
+   * Instantiate a presenter for a single entity and wrap it in a Proxy so
+   * every raw attribute not shadowed by a getter passes through
+   * automatically.
+   */
+  static present(data, context, options) {
+    const presenter = new this(data, context);
+    return createDataProxy(presenter, data, options);
+  }
+  /** Present a collection: `UserPresenter.presentMany(rawUsers)`. */
+  static presentMany(dataList, context, options) {
+    return dataList.map(
+      (item) => (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.present(item, context, options)
+      )
+    );
+  }
+  /**
+   * Resolve every async computed property and merge it with the sync
+   * getters into a single plain, JSON-serializable object.
+   *
+   * JavaScript has no `async get` syntax, so async computed properties are
+   * plain `async` methods instead:
+   *
+   * ```ts
+   * class UserPresenter extends Presenter<User> {
+   *   async profileScore() {
+   *     return calculateScore(this.data);
+   *   }
+   * }
+   *
+   * const resolved = await UserPresenter.present(user).resolve();
+   * resolved.profileScore; // number
+   * ```
+   *
+   * `resolve()` auto-detects any `async` method on the presenter — no
+   * extra registration needed — calls each with no arguments, and merges
+   * the results with `toJSON()`. A rejected async property resolves to
+   * `undefined` rather than failing the whole call.
+   */
+  async resolve(options) {
+    const asyncKeys = getAsyncMethodNames(this, _Presenter);
+    const resolvedEntries = await Promise.all(
+      asyncKeys.map(async (key) => {
+        try {
+          const method = this[key];
+          return [key, await method.call(this)];
+        } catch {
+          return [key, void 0];
+        }
+      })
+    );
+    return {
+      ...this.toJSON(options),
+      ...Object.fromEntries(resolvedEntries)
+    };
+  }
+  /**
+   * Serialize the presenter's own computed getters (never the raw
+   * `data`/`context`) to a plain object. Safe to return from a Next.js
+   * Server Action or pass as props to a Client Component.
+   */
+  toJSON(options) {
+    return serializePresenter(this, _Presenter, options);
+  }
+  /** `presenter.only("id", "fullName", "avatarUrl")` */
+  only(...keys) {
+    return this.toJSON({ only: keys });
+  }
+  /** `presenter.except("internalNotes")` */
+  except(...keys) {
+    return this.toJSON({ except: keys });
+  }
+};
+
+// src/decorate.ts
+function decorate(data, PresenterClass, context, options) {
+  return PresenterClass.present(data, context, options);
+}
+function decorateMany(dataList, PresenterClass, context, options) {
+  return dataList.map((item) => decorate(item, PresenterClass, context, options));
+}
+
+exports.Presenter = Presenter;
+exports.configurePresenter = configurePresenter;
+exports.createFormatAdapter = createFormatAdapter;
+exports.decorate = decorate;
+exports.decorateMany = decorateMany;
+exports.getPresenterConfig = getPresenterConfig;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/proxy.ts","../src/reflection.ts","../src/serialize.ts","../src/config.ts","../src/format.ts","../src/Presenter.ts","../src/decorate.ts"],"names":[],"mappings":";;;AAEA,IAAM,SAAA,uBAAgB,OAAA,EAAsC;AAUrD,SAAS,eAAA,CACd,SAAA,EACA,IAAA,EACA,OAAA,GAA0B,EAAC,EACpB;AACP,EAAA,OAAO,IAAI,MAAM,SAAA,EAAW;AAAA,IAC1B,GAAA,CAAI,MAAA,EAAQ,QAAA,EAAU,QAAA,EAAU;AAC9B,MAAA,IAAI,YAAY,MAAA,EAAQ;AACtB,QAAA,IAAI,OAAA,CAAQ,OAAA,IAAW,OAAO,QAAA,KAAa,QAAA,EAAU;AACnD,UAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,cAAA,CAAe,MAAM,CAAA;AAC1C,UAAA,MAAM,aAAa,KAAA,GAAQ,MAAA,CAAO,wBAAA,CAAyB,KAAA,EAAO,QAAQ,CAAA,GAAI,MAAA;AAC9E,UAAA,IAAI,UAAA,IAAc,OAAO,UAAA,CAAW,GAAA,KAAQ,UAAA,EAAY;AACtD,YAAA,IAAI,KAAA,GAAQ,SAAA,CAAU,GAAA,CAAI,MAAM,CAAA;AAChC,YAAA,IAAI,CAAC,KAAA,EAAO;AACV,cAAA,KAAA,uBAAY,GAAA,EAAI;AAChB,cAAA,SAAA,CAAU,GAAA,CAAI,QAAQ,KAAK,CAAA;AAAA,YAC7B;AACA,YAAA,IAAI,KAAA,CAAM,GAAA,CAAI,QAAQ,CAAA,EAAG;AACvB,cAAA,OAAO,KAAA,CAAM,IAAI,QAAQ,CAAA;AAAA,YAC3B;AACA,YAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,MAAA,EAAQ,UAAU,QAAQ,CAAA;AACpD,YAAA,KAAA,CAAM,GAAA,CAAI,UAAU,KAAK,CAAA;AACzB,YAAA,OAAO,KAAA;AAAA,UACT;AAAA,QACF;AACA,QAAA,OAAO,OAAA,CAAQ,GAAA,CAAI,MAAA,EAAQ,QAAA,EAAU,QAAQ,CAAA;AAAA,MAC/C;AAEA,MAAA,IACE,OAAO,aAAa,QAAA,IACpB,IAAA,KAAS,QACT,OAAO,IAAA,KAAS,QAAA,IAChB,QAAA,IAAa,IAAA,EACb;AACA,QAAA,OAAQ,KAAiC,QAAQ,CAAA;AAAA,MACnD;AAEA,MAAA,OAAO,MAAA;AAAA,IACT,CAAA;AAAA,IAEA,GAAA,CAAI,QAAQ,QAAA,EAAU;AACpB,MAAA,IAAI,QAAA,IAAY,QAAQ,OAAO,IAAA;AAC/B,MAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,OAAO,IAAA,KAAS,QAAA,EAAU;AAC7C,QAAA,OAAO,QAAA,IAAa,IAAA;AAAA,MACtB;AACA,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,GACD,CAAA;AACH;;;AC5DA,IAAM,aAAA,mBAAgB,IAAI,GAAA,CAAI,CAAC,aAAa,CAAC,CAAA;AAQtC,SAAS,cAAA,CAAe,UAAkB,MAAA,EAA4B;AAC3E,EAAA,MAAM,KAAA,uBAAY,GAAA,EAAY;AAC9B,EAAA,IAAI,KAAA,GAAuB,MAAA,CAAO,cAAA,CAAe,QAAQ,CAAA;AAEzD,EAAA,OAAO,KAAA,IAAS,KAAA,KAAU,MAAA,CAAO,SAAA,EAAW;AAC1C,IAAA,IAAI,KAAA,KAAU,OAAO,SAAA,EAAW;AAEhC,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,UAAU,CAAA,IAAK,MAAA,CAAO,QAAQ,MAAA,CAAO,yBAAA,CAA0B,KAAK,CAAC,CAAA,EAAG;AACvF,MAAA,IAAI,CAAC,cAAc,GAAA,CAAI,GAAG,KAAK,OAAO,UAAA,CAAW,QAAQ,UAAA,EAAY;AACnE,QAAA,KAAA,CAAM,IAAI,GAAG,CAAA;AAAA,MACf;AAAA,IACF;AAEA,IAAA,KAAA,GAAQ,MAAA,CAAO,eAAe,KAAK,CAAA;AAAA,EACrC;AAEA,EAAA,OAAO,KAAA,CAAM,KAAK,KAAK,CAAA;AACzB;AAQO,SAAS,mBAAA,CAAoB,UAAkB,MAAA,EAA4B;AAChF,EAAA,MAAM,KAAA,uBAAY,GAAA,EAAY;AAC9B,EAAA,IAAI,KAAA,GAAuB,MAAA,CAAO,cAAA,CAAe,QAAQ,CAAA;AAEzD,EAAA,OAAO,KAAA,IAAS,KAAA,KAAU,MAAA,CAAO,SAAA,EAAW;AAC1C,IAAA,IAAI,KAAA,KAAU,OAAO,SAAA,EAAW;AAEhC,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,UAAU,CAAA,IAAK,MAAA,CAAO,QAAQ,MAAA,CAAO,yBAAA,CAA0B,KAAK,CAAC,CAAA,EAAG;AACvF,MAAA,IACE,CAAC,aAAA,CAAc,GAAA,CAAI,GAAG,CAAA,IACtB,OAAO,UAAA,CAAW,KAAA,KAAU,UAAA,IAC5B,UAAA,CAAW,KAAA,CAAM,WAAA,EAAa,SAAS,eAAA,EACvC;AACA,QAAA,KAAA,CAAM,IAAI,GAAG,CAAA;AAAA,MACf;AAAA,IACF;AAEA,IAAA,KAAA,GAAQ,MAAA,CAAO,eAAe,KAAK,CAAA;AAAA,EACrC;AAEA,EAAA,OAAO,KAAA,CAAM,KAAK,KAAK,CAAA;AACzB;;;ACvCO,SAAS,kBAAA,CACd,SAAA,EACA,MAAA,EACA,OAAA,GAAyB,EAAC,EACD;AACzB,EAAA,MAAM,OAAA,GAAU,cAAA,CAAe,SAAA,EAAW,MAAM,CAAA;AAChD,EAAA,MAAM,UAAU,OAAA,CAAQ,IAAA,GAAO,IAAI,GAAA,CAAI,OAAA,CAAQ,IAAI,CAAA,GAAI,IAAA;AACvD,EAAA,MAAM,YAAY,OAAA,CAAQ,MAAA,GAAS,IAAI,GAAA,CAAI,OAAA,CAAQ,MAAM,CAAA,GAAI,IAAA;AAE7D,EAAA,MAAM,WAAA,GAAc,OAAA,CAAQ,MAAA,CAAO,CAAC,GAAA,KAAQ;AAC1C,IAAA,IAAI,WAAW,CAAC,OAAA,CAAQ,GAAA,CAAI,GAAG,GAAG,OAAO,KAAA;AACzC,IAAA,IAAI,SAAA,IAAa,SAAA,CAAU,GAAA,CAAI,GAAG,GAAG,OAAO,KAAA;AAC5C,IAAA,OAAO,IAAA;AAAA,EACT,CAAC,CAAA;AAGD,EAAA,MAAM,WAAA,GAAc,OAAA,GAChB,KAAA,CAAM,IAAA,CAAK,OAAO,CAAA,CAAE,MAAA,CAAO,CAAC,GAAA,KAAQ,WAAA,CAAY,QAAA,CAAS,GAAG,CAAC,CAAA,GAC7D,WAAA;AAEJ,EAAA,MAAM,SAAkC,EAAC;AACzC,EAAA,KAAA,MAAW,OAAO,WAAA,EAAa;AAC7B,IAAA,IAAI;AACF,MAAA,MAAA,CAAO,GAAG,CAAA,GAAK,SAAA,CAAsC,GAAG,CAAA;AAAA,IAC1D,CAAA,CAAA,MAAQ;AACN,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,MAAA;AAAA,IAChB;AAAA,EACF;AACA,EAAA,OAAO,MAAA;AACT;;;AC1CA,IAAI,YAAA,GAAsC;AAAA,EACxC,MAAA,EAAQ;AACV,CAAA;AAaO,SAAS,mBAAmB,MAAA,EAAqC;AACtE,EAAA,YAAA,GAAe,EAAE,GAAG,YAAA,EAAc,GAAG,MAAA,EAAO;AAC9C;AAEO,SAAS,kBAAA,GAA4C;AAC1D,EAAA,OAAO,YAAA;AACT;AAGO,IAAM,gBAAA,GAAgC,CAAC,GAAA,KAAQ,GAAA;;;ACvBtD,SAAS,OAAO,KAAA,EAAqC;AACnD,EAAA,OAAO,KAAA,YAAiB,IAAA,GAAO,KAAA,GAAQ,IAAI,KAAK,KAAK,CAAA;AACvD;AAEA,IAAM,oBAAA,GAA+C;AAAA,EACnD,IAAA,EAAM,GAAA,GAAO,EAAA,GAAK,EAAA,GAAK,EAAA,GAAK,GAAA;AAAA,EAC5B,OAAA,EAAS,GAAA,GAAO,EAAA,GAAK,EAAA,GAAK,EAAA,GAAK,EAAA;AAAA,EAC/B,KAAA,EAAO,GAAA,GAAO,EAAA,GAAK,EAAA,GAAK,EAAA,GAAK,EAAA;AAAA,EAC7B,IAAA,EAAM,GAAA,GAAO,EAAA,GAAK,EAAA,GAAK,EAAA,GAAK,CAAA;AAAA,EAC5B,GAAA,EAAK,GAAA,GAAO,EAAA,GAAK,EAAA,GAAK,EAAA;AAAA,EACtB,IAAA,EAAM,MAAO,EAAA,GAAK,EAAA;AAAA,EAClB,QAAQ,GAAA,GAAO,EAAA;AAAA,EACf,MAAA,EAAQ;AACV,CAAA;AAOO,SAAS,oBAAoB,MAAA,EAAgC;AAClE,EAAA,MAAM,SAAS,kBAAA,EAAmB;AAClC,EAAA,MAAM,cAAA,GAAiB,MAAA,IAAU,MAAA,CAAO,MAAA,IAAU,OAAA;AAClD,EAAA,MAAM,SAAA,GAAY,MAAA,CAAO,UAAA,IAAc,EAAC;AAExC,EAAA,MAAM,IAAA,GAAsB;AAAA,IAC1B,IAAA,CAAK,OAAO,OAAA,EAAS;AACnB,MAAA,OAAO,IAAI,KAAK,cAAA,CAAe,cAAA,EAAgB,OAAO,CAAA,CAAE,MAAA,CAAO,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,IAC9E,CAAA;AAAA,IACA,MAAA,CAAO,OAAO,OAAA,EAAS;AACrB,MAAA,OAAO,IAAI,IAAA,CAAK,YAAA,CAAa,gBAAgB,OAAO,CAAA,CAAE,OAAO,KAAK,CAAA;AAAA,IACpE,CAAA;AAAA,IACA,QAAA,CAAS,KAAA,EAAO,QAAA,GAAW,KAAA,EAAO,OAAA,EAAS;AACzC,MAAA,OAAO,IAAI,IAAA,CAAK,YAAA,CAAa,cAAA,EAAgB;AAAA,QAC3C,KAAA,EAAO,UAAA;AAAA,QACP,QAAA;AAAA,QACA,GAAG;AAAA,OACJ,CAAA,CAAE,MAAA,CAAO,KAAK,CAAA;AAAA,IACjB,CAAA;AAAA,IACA,YAAA,CAAa,KAAA,EAAO,IAAA,GAAO,KAAA,EAAO;AAChC,MAAA,MAAM,IAAA,GAAO,OAAO,KAAK,CAAA;AACzB,MAAA,MAAM,MAAA,GAAS,IAAA,CAAK,OAAA,EAAQ,GAAI,KAAK,GAAA,EAAI;AACzC,MAAA,MAAM,OAAA,GAAU,oBAAA,CAAqB,IAAI,CAAA,IAAK,oBAAA,CAAqB,GAAA;AACnE,MAAA,MAAM,GAAA,GAAM,IAAI,IAAA,CAAK,kBAAA,CAAmB,gBAAgB,EAAE,OAAA,EAAS,QAAQ,CAAA;AAC3E,MAAA,OAAO,IAAI,MAAA,CAAO,IAAA,CAAK,MAAM,MAAA,GAAS,OAAO,GAAG,IAAI,CAAA;AAAA,IACtD;AAAA,GACF;AAEA,EAAA,OAAO,EAAE,GAAG,IAAA,EAAM,GAAG,SAAA,EAAU;AACjC;;;AC7BO,IAAe,SAAA,GAAf,MAAe,UAAA,CAA4B;AAAA,EAIhD,WAAA,CAAY,MAAS,OAAA,EAAa;AAChC,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAA,CAAK,OAAA,GAAW,WAAY,EAAC;AAAA,EAC/B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAc,MAAA,GAAS;AACrB,IAAA,MAAM,MAAA,GAAU,KAAK,OAAA,EAAmC,MAAA;AACxD,IAAA,OAAO,oBAAoB,MAAM,CAAA;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQU,CAAA,CAAE,KAAa,MAAA,EAA4B;AACnD,IAAA,MAAM,SAAS,kBAAA,EAAmB;AAClC,IAAA,MAAM,SAAA,GAAY,OAAO,SAAA,IAAa,gBAAA;AACtC,IAAA,MAAM,MAAA,GAAU,KAAK,OAAA,EAAmC,MAAA;AACxD,IAAA,OAAO,SAAA,CAAU,GAAA,EAAK,MAAA,EAAQ,MAAA,IAAU,OAAO,MAAM,CAAA;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,OAAA,CAEL,IAAA,EACA,OAAA,EACA,OAAA,EACe;AAEf,IAAA,MAAM,SAAA,GAAY,IAAI,IAAA,CAAK,IAAA,EAAM,OAAO,CAAA;AACxC,IAAA,OAAO,eAAA,CAAgB,SAAA,EAAW,IAAA,EAAM,OAAO,CAAA;AAAA,EACjD;AAAA;AAAA,EAGA,OAAO,WAAA,CAEL,QAAA,EACA,OAAA,EACA,OAAA,EACsB;AACtB,IAAA,OAAO,QAAA,CAAS,GAAA;AAAA,MAAI,CAAC,IAAA;AAAA;AAAA,QAElB,IAAA,CAAa,OAAA,CAAQ,IAAA,EAAM,OAAA,EAAS,OAAO;AAAA;AAAA,KAC9C;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAyBA,MAAM,QAA+B,OAAA,EAA2D;AAC9F,IAAA,MAAM,SAAA,GAAY,mBAAA,CAAoB,IAAA,EAAM,UAAS,CAAA;AAErD,IAAA,MAAM,eAAA,GAAkB,MAAM,OAAA,CAAQ,GAAA;AAAA,MACpC,SAAA,CAAU,GAAA,CAAI,OAAO,GAAA,KAAQ;AAC3B,QAAA,IAAI;AACF,UAAA,MAAM,MAAA,GAAU,KAA2D,GAAG,CAAA;AAC9E,UAAA,OAAO,CAAC,GAAA,EAAK,MAAM,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,QACtC,CAAA,CAAA,MAAQ;AACN,UAAA,OAAO,CAAC,KAAK,MAAS,CAAA;AAAA,QACxB;AAAA,MACF,CAAC;AAAA,KACH;AAEA,IAAA,OAAO;AAAA,MACL,GAAG,IAAA,CAAK,MAAA,CAAO,OAAO,CAAA;AAAA,MACtB,GAAG,MAAA,CAAO,WAAA,CAAY,eAAe;AAAA,KACvC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,OAAA,EAAkD;AACvD,IAAA,OAAO,kBAAA,CAAmB,IAAA,EAAM,UAAA,EAAW,OAAO,CAAA;AAAA,EACpD;AAAA;AAAA,EAGA,QAAQ,IAAA,EAAyC;AAC/C,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,EAAE,IAAA,EAAM,MAAM,CAAA;AAAA,EACnC;AAAA;AAAA,EAGA,UAAU,IAAA,EAAyC;AACjD,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,EAAE,MAAA,EAAQ,MAAM,CAAA;AAAA,EACrC;AACF;;;ACrIO,SAAS,QAAA,CACd,IAAA,EACA,cAAA,EACA,OAAA,EACA,OAAA,EACO;AAEP,EAAA,OAAQ,cAAA,CAAuB,OAAA,CAAQ,IAAA,EAAM,OAAA,EAAS,OAAO,CAAA;AAC/D;AAGO,SAAS,YAAA,CACd,QAAA,EACA,cAAA,EACA,OAAA,EACA,OAAA,EACc;AACd,EAAA,OAAO,QAAA,CAAS,IAAI,CAAC,IAAA,KAAS,SAAS,IAAA,EAAM,cAAA,EAAgB,OAAA,EAAS,OAAO,CAAC,CAAA;AAChF","file":"index.cjs","sourcesContent":["import type { PresentOptions } from \"./types\";\n\nconst memoCache = new WeakMap<object, Map<string, unknown>>();\n\n/**\n * Wrap a presenter instance so that reading any property first checks the\n * presenter itself (its getters/methods win), and falls back to the same\n * property on the raw `data` object if the presenter doesn't define it.\n * This is what lets `UserPresenter.present(user).email` work without\n * writing `get email() { return this.data.email }` for every field\n * (use case 10).\n */\nexport function createDataProxy<P extends object, T>(\n  presenter: P,\n  data: T,\n  options: PresentOptions = {}\n): P & T {\n  return new Proxy(presenter, {\n    get(target, property, receiver) {\n      if (property in target) {\n        if (options.memoize && typeof property === \"string\") {\n          const proto = Object.getPrototypeOf(target);\n          const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, property) : undefined;\n          if (descriptor && typeof descriptor.get === \"function\") {\n            let cache = memoCache.get(target);\n            if (!cache) {\n              cache = new Map();\n              memoCache.set(target, cache);\n            }\n            if (cache.has(property)) {\n              return cache.get(property);\n            }\n            const value = Reflect.get(target, property, receiver);\n            cache.set(property, value);\n            return value;\n          }\n        }\n        return Reflect.get(target, property, receiver);\n      }\n\n      if (\n        typeof property === \"string\" &&\n        data !== null &&\n        typeof data === \"object\" &&\n        property in (data as object)\n      ) {\n        return (data as Record<string, unknown>)[property];\n      }\n\n      return undefined;\n    },\n\n    has(target, property) {\n      if (property in target) return true;\n      if (data !== null && typeof data === \"object\") {\n        return property in (data as object);\n      }\n      return false;\n    },\n  }) as P & T;\n}\n","const EXCLUDED_KEYS = new Set([\"constructor\"]);\n\n/**\n * Collect every `get` accessor defined anywhere in `instance`'s prototype\n * chain, up to (but not including) `stopAt`'s own prototype. This is how\n * `toJSON()` / `only()` / `except()` know which properties are\n * presenter-defined (as opposed to raw pass-through data attributes).\n */\nexport function getGetterNames(instance: object, stopAt: Function): string[] {\n  const names = new Set<string>();\n  let proto: object | null = Object.getPrototypeOf(instance);\n\n  while (proto && proto !== Object.prototype) {\n    if (proto === stopAt.prototype) break;\n\n    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {\n      if (!EXCLUDED_KEYS.has(key) && typeof descriptor.get === \"function\") {\n        names.add(key);\n      }\n    }\n\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  return Array.from(names);\n}\n\n/**\n * Collect every plain `async` method (not accessor — JS has no\n * `async get`) defined anywhere in `instance`'s prototype chain, up to\n * `stopAt`. Used by `resolve()` to auto-discover async computed\n * properties without requiring any extra registration from the user.\n */\nexport function getAsyncMethodNames(instance: object, stopAt: Function): string[] {\n  const names = new Set<string>();\n  let proto: object | null = Object.getPrototypeOf(instance);\n\n  while (proto && proto !== Object.prototype) {\n    if (proto === stopAt.prototype) break;\n\n    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {\n      if (\n        !EXCLUDED_KEYS.has(key) &&\n        typeof descriptor.value === \"function\" &&\n        descriptor.value.constructor?.name === \"AsyncFunction\"\n      ) {\n        names.add(key);\n      }\n    }\n\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  return Array.from(names);\n}\n","import type { ToJSONOptions } from \"./types\";\nimport { getGetterNames } from \"./reflection\";\n\n/**\n * Serialize a presenter to a plain object containing only its own\n * computed getters — never the raw `data`/`context`, and never a getter\n * that isn't defined on the presenter itself. This is what makes\n * `toJSON()` safe to send across a server action / API boundary: it can\n * never accidentally leak the full underlying entity.\n *\n * A getter that throws (e.g. an authorization check like\n * `if (!this.context.currentUser.can(...)) throw ...`) is treated the\n * same as one that returns `undefined` — it's simply omitted from the\n * output rather than blowing up serialization for the whole object.\n */\nexport function serializePresenter<P extends object>(\n  presenter: P,\n  stopAt: Function,\n  options: ToJSONOptions = {}\n): Record<string, unknown> {\n  const allKeys = getGetterNames(presenter, stopAt);\n  const onlySet = options.only ? new Set(options.only) : null;\n  const exceptSet = options.except ? new Set(options.except) : null;\n\n  const allowedKeys = allKeys.filter((key) => {\n    if (onlySet && !onlySet.has(key)) return false;\n    if (exceptSet && exceptSet.has(key)) return false;\n    return true;\n  });\n\n  // Preserve the order the caller asked for in `only`, when given.\n  const orderedKeys = onlySet\n    ? Array.from(onlySet).filter((key) => allowedKeys.includes(key))\n    : allowedKeys;\n\n  const result: Record<string, unknown> = {};\n  for (const key of orderedKeys) {\n    try {\n      result[key] = (presenter as Record<string, unknown>)[key];\n    } catch {\n      result[key] = undefined;\n    }\n  }\n  return result;\n}\n","import type { PresenterGlobalConfig, TranslateFn } from \"./types\";\n\nlet globalConfig: PresenterGlobalConfig = {\n  locale: \"en-US\",\n};\n\n/**\n * Wire up your app's i18n library / default locale / formatter overrides\n * once, e.g. in a root layout or app entry point:\n *\n * ```ts\n * configurePresenter({\n *   translate: (key, params, locale) => i18next.t(key, { ...params, lng: locale }),\n *   locale: \"en-US\",\n * });\n * ```\n */\nexport function configurePresenter(config: PresenterGlobalConfig): void {\n  globalConfig = { ...globalConfig, ...config };\n}\n\nexport function getPresenterConfig(): PresenterGlobalConfig {\n  return globalConfig;\n}\n\n/** Identity fallback so `this.t(key)` is always safe to call. */\nexport const defaultTranslate: TranslateFn = (key) => key;\n","import type { FormatAdapter } from \"./types\";\nimport { getPresenterConfig } from \"./config\";\n\nfunction toDate(value: Date | string | number): Date {\n  return value instanceof Date ? value : new Date(value);\n}\n\nconst RELATIVE_DIVISORS_MS: Record<string, number> = {\n  year: 1000 * 60 * 60 * 24 * 365,\n  quarter: 1000 * 60 * 60 * 24 * 91,\n  month: 1000 * 60 * 60 * 24 * 30,\n  week: 1000 * 60 * 60 * 24 * 7,\n  day: 1000 * 60 * 60 * 24,\n  hour: 1000 * 60 * 60,\n  minute: 1000 * 60,\n  second: 1000,\n};\n\n/**\n * Build a locale-aware formatter. Presenters call this via `this.format`,\n * automatically passing `context.locale` — you rarely need to call it\n * directly.\n */\nexport function createFormatAdapter(locale?: string): FormatAdapter {\n  const config = getPresenterConfig();\n  const resolvedLocale = locale ?? config.locale ?? \"en-US\";\n  const overrides = config.formatters ?? {};\n\n  const base: FormatAdapter = {\n    date(value, options) {\n      return new Intl.DateTimeFormat(resolvedLocale, options).format(toDate(value));\n    },\n    number(value, options) {\n      return new Intl.NumberFormat(resolvedLocale, options).format(value);\n    },\n    currency(value, currency = \"USD\", options) {\n      return new Intl.NumberFormat(resolvedLocale, {\n        style: \"currency\",\n        currency,\n        ...options,\n      }).format(value);\n    },\n    relativeTime(value, unit = \"day\") {\n      const date = toDate(value);\n      const diffMs = date.getTime() - Date.now();\n      const divisor = RELATIVE_DIVISORS_MS[unit] ?? RELATIVE_DIVISORS_MS.day;\n      const rtf = new Intl.RelativeTimeFormat(resolvedLocale, { numeric: \"auto\" });\n      return rtf.format(Math.round(diffMs / divisor), unit);\n    },\n  };\n\n  return { ...base, ...overrides };\n}\n","import type { AnyRecord, ContextOf, DataOf, PresentOptions, ToJSONOptions } from \"./types\";\nimport { createDataProxy } from \"./proxy\";\nimport { getAsyncMethodNames } from \"./reflection\";\nimport { serializePresenter } from \"./serialize\";\nimport { createFormatAdapter } from \"./format\";\nimport { defaultTranslate, getPresenterConfig } from \"./config\";\n\n/**\n * Base class for all presenters/decorators.\n *\n * ```ts\n * class ProductPresenter extends Presenter<Product> {\n *   get isNew() {\n *     const days = (Date.now() - new Date(this.data.created_at).getTime()) / 86_400_000;\n *     return days <= 7;\n *   }\n * }\n *\n * const product = ProductPresenter.present(rawProduct);\n * product.isNew;        // presenter getter\n * product.seller;       // passed through from rawProduct automatically\n * ```\n */\nexport abstract class Presenter<T, C = AnyRecord> {\n  readonly data: T;\n  readonly context: C;\n\n  constructor(data: T, context?: C) {\n    this.data = data;\n    this.context = (context ?? ({} as C)) as C;\n  }\n\n  /**\n   * Intl-backed date/number/currency/relative-time formatting, aware of\n   * `context.locale`. Override globally via `configurePresenter`.\n   */\n  protected get format() {\n    const locale = (this.context as AnyRecord | undefined)?.locale as string | undefined;\n    return createFormatAdapter(locale);\n  }\n\n  /**\n   * Translate a key via the globally configured `translate` function\n   * (wire up i18next / next-intl / FormatJS / etc. once with\n   * `configurePresenter({ translate })`). Falls back to returning the key\n   * itself if nothing is configured, so it's always safe to call.\n   */\n  protected t(key: string, params?: AnyRecord): string {\n    const config = getPresenterConfig();\n    const translate = config.translate ?? defaultTranslate;\n    const locale = (this.context as AnyRecord | undefined)?.locale as string | undefined;\n    return translate(key, params, locale ?? config.locale);\n  }\n\n  /**\n   * Instantiate a presenter for a single entity and wrap it in a Proxy so\n   * every raw attribute not shadowed by a getter passes through\n   * automatically.\n   */\n  static present<P extends Presenter<any, any>>(\n    this: new (data: DataOf<P>, context?: ContextOf<P>) => P,\n    data: DataOf<P>,\n    context?: ContextOf<P>,\n    options?: PresentOptions\n  ): P & DataOf<P> {\n    // eslint-disable-next-line new-cap\n    const presenter = new this(data, context);\n    return createDataProxy(presenter, data, options);\n  }\n\n  /** Present a collection: `UserPresenter.presentMany(rawUsers)`. */\n  static presentMany<P extends Presenter<any, any>>(\n    this: new (data: DataOf<P>, context?: ContextOf<P>) => P,\n    dataList: readonly DataOf<P>[],\n    context?: ContextOf<P>,\n    options?: PresentOptions\n  ): Array<P & DataOf<P>> {\n    return dataList.map((item) =>\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      (this as any).present(item, context, options)\n    );\n  }\n\n  /**\n   * Resolve every async computed property and merge it with the sync\n   * getters into a single plain, JSON-serializable object.\n   *\n   * JavaScript has no `async get` syntax, so async computed properties are\n   * plain `async` methods instead:\n   *\n   * ```ts\n   * class UserPresenter extends Presenter<User> {\n   *   async profileScore() {\n   *     return calculateScore(this.data);\n   *   }\n   * }\n   *\n   * const resolved = await UserPresenter.present(user).resolve();\n   * resolved.profileScore; // number\n   * ```\n   *\n   * `resolve()` auto-detects any `async` method on the presenter — no\n   * extra registration needed — calls each with no arguments, and merges\n   * the results with `toJSON()`. A rejected async property resolves to\n   * `undefined` rather than failing the whole call.\n   */\n  async resolve(this: Presenter<T, C>, options?: ToJSONOptions): Promise<Record<string, unknown>> {\n    const asyncKeys = getAsyncMethodNames(this, Presenter);\n\n    const resolvedEntries = await Promise.all(\n      asyncKeys.map(async (key) => {\n        try {\n          const method = (this as unknown as Record<string, () => Promise<unknown>>)[key];\n          return [key, await method.call(this)] as const;\n        } catch {\n          return [key, undefined] as const;\n        }\n      })\n    );\n\n    return {\n      ...this.toJSON(options),\n      ...Object.fromEntries(resolvedEntries),\n    };\n  }\n\n  /**\n   * Serialize the presenter's own computed getters (never the raw\n   * `data`/`context`) to a plain object. Safe to return from a Next.js\n   * Server Action or pass as props to a Client Component.\n   */\n  toJSON(options?: ToJSONOptions): Record<string, unknown> {\n    return serializePresenter(this, Presenter, options);\n  }\n\n  /** `presenter.only(\"id\", \"fullName\", \"avatarUrl\")` */\n  only(...keys: string[]): Record<string, unknown> {\n    return this.toJSON({ only: keys });\n  }\n\n  /** `presenter.except(\"internalNotes\")` */\n  except(...keys: string[]): Record<string, unknown> {\n    return this.toJSON({ except: keys });\n  }\n}\n","import type { Presenter } from \"./Presenter\";\nimport type { PresentOptions, PresenterConstructor } from \"./types\";\n\n/**\n * Functional, Rails-`decorate`-style alternative to `Presenter.present`:\n *\n * ```ts\n * import { decorate } from \"react-presenter\";\n * const user = decorate(rawUser, UserPresenter);\n * ```\n */\nexport function decorate<T, C, P extends Presenter<T, C>>(\n  data: T,\n  PresenterClass: PresenterConstructor<T, C, P>,\n  context?: C,\n  options?: PresentOptions\n): P & T {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return (PresenterClass as any).present(data, context, options);\n}\n\n/** Functional equivalent of `presentMany`. */\nexport function decorateMany<T, C, P extends Presenter<T, C>>(\n  dataList: readonly T[],\n  PresenterClass: PresenterConstructor<T, C, P>,\n  context?: C,\n  options?: PresentOptions\n): Array<P & T> {\n  return dataList.map((item) => decorate(item, PresenterClass, context, options));\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+type AnyRecord = Record<string, unknown>;
+/**
+ * Shape tsc needs to accept a presenter class as a value (e.g. in
+ * `decorate(data, UserPresenter)` or `usePresenter(UserPresenter, data)`),
+ * so `T`/`C`/`P` can be inferred from the class that's passed in.
+ */
+interface PresenterConstructor<T, C, P> {
+    new (data: T, context?: C): P;
+}
+/**
+ * Extract a presenter's `data` type from the presenter type itself. Used
+ * so that `SomePresenter.present(data, context)` infers `T`/`C` from the
+ * concrete subclass (`this`) rather than independently from whatever gets
+ * passed at the call site — which is what lets a partial context object
+ * literal type-check against the presenter's declared context type.
+ */
+type DataOf<P> = P extends {
+    data: infer T;
+} ? T : never;
+type ContextOf<P> = P extends {
+    context: infer C;
+} ? C : never;
+interface PresentOptions {
+    /**
+     * Cache each getter's return value the first time it's read on a given
+     * presenter instance. Useful when a computed getter is expensive (e.g.
+     * heavy formatting or derived aggregation) and may be read more than
+     * once during a render. Off by default because most getters are cheap
+     * and memoizing can hide the fact that `data` changed underneath you.
+     */
+    memoize?: boolean;
+}
+interface ToJSONOptions {
+    /** Only include these presenter properties, in the given order. */
+    only?: readonly string[];
+    /** Include every presenter property except these. */
+    except?: readonly string[];
+}
+interface FormatAdapter {
+    date(value: Date | string | number, options?: Intl.DateTimeFormatOptions): string;
+    number(value: number, options?: Intl.NumberFormatOptions): string;
+    currency(value: number, currency?: string, options?: Intl.NumberFormatOptions): string;
+    relativeTime(value: Date | string | number, unit?: Intl.RelativeTimeFormatUnit): string;
+}
+type TranslateFn = (key: string, params?: AnyRecord, locale?: string) => string;
+interface PresenterGlobalConfig {
+    /** Plug in your i18n library (i18next, next-intl, FormatJS, ...) here. */
+    translate?: TranslateFn;
+    /** Fallback locale used when a presenter's context has none. */
+    locale?: string;
+    /** Override individual Intl-backed formatters globally. */
+    formatters?: Partial<FormatAdapter>;
+}
+
+/**
+ * Base class for all presenters/decorators.
+ *
+ * ```ts
+ * class ProductPresenter extends Presenter<Product> {
+ *   get isNew() {
+ *     const days = (Date.now() - new Date(this.data.created_at).getTime()) / 86_400_000;
+ *     return days <= 7;
+ *   }
+ * }
+ *
+ * const product = ProductPresenter.present(rawProduct);
+ * product.isNew;        // presenter getter
+ * product.seller;       // passed through from rawProduct automatically
+ * ```
+ */
+declare abstract class Presenter<T, C = AnyRecord> {
+    readonly data: T;
+    readonly context: C;
+    constructor(data: T, context?: C);
+    /**
+     * Intl-backed date/number/currency/relative-time formatting, aware of
+     * `context.locale`. Override globally via `configurePresenter`.
+     */
+    protected get format(): FormatAdapter;
+    /**
+     * Translate a key via the globally configured `translate` function
+     * (wire up i18next / next-intl / FormatJS / etc. once with
+     * `configurePresenter({ translate })`). Falls back to returning the key
+     * itself if nothing is configured, so it's always safe to call.
+     */
+    protected t(key: string, params?: AnyRecord): string;
+    /**
+     * Instantiate a presenter for a single entity and wrap it in a Proxy so
+     * every raw attribute not shadowed by a getter passes through
+     * automatically.
+     */
+    static present<P extends Presenter<any, any>>(this: new (data: DataOf<P>, context?: ContextOf<P>) => P, data: DataOf<P>, context?: ContextOf<P>, options?: PresentOptions): P & DataOf<P>;
+    /** Present a collection: `UserPresenter.presentMany(rawUsers)`. */
+    static presentMany<P extends Presenter<any, any>>(this: new (data: DataOf<P>, context?: ContextOf<P>) => P, dataList: readonly DataOf<P>[], context?: ContextOf<P>, options?: PresentOptions): Array<P & DataOf<P>>;
+    /**
+     * Resolve every async computed property and merge it with the sync
+     * getters into a single plain, JSON-serializable object.
+     *
+     * JavaScript has no `async get` syntax, so async computed properties are
+     * plain `async` methods instead:
+     *
+     * ```ts
+     * class UserPresenter extends Presenter<User> {
+     *   async profileScore() {
+     *     return calculateScore(this.data);
+     *   }
+     * }
+     *
+     * const resolved = await UserPresenter.present(user).resolve();
+     * resolved.profileScore; // number
+     * ```
+     *
+     * `resolve()` auto-detects any `async` method on the presenter — no
+     * extra registration needed — calls each with no arguments, and merges
+     * the results with `toJSON()`. A rejected async property resolves to
+     * `undefined` rather than failing the whole call.
+     */
+    resolve(this: Presenter<T, C>, options?: ToJSONOptions): Promise<Record<string, unknown>>;
+    /**
+     * Serialize the presenter's own computed getters (never the raw
+     * `data`/`context`) to a plain object. Safe to return from a Next.js
+     * Server Action or pass as props to a Client Component.
+     */
+    toJSON(options?: ToJSONOptions): Record<string, unknown>;
+    /** `presenter.only("id", "fullName", "avatarUrl")` */
+    only(...keys: string[]): Record<string, unknown>;
+    /** `presenter.except("internalNotes")` */
+    except(...keys: string[]): Record<string, unknown>;
+}
+
+/**
+ * Functional, Rails-`decorate`-style alternative to `Presenter.present`:
+ *
+ * ```ts
+ * import { decorate } from "react-presenter";
+ * const user = decorate(rawUser, UserPresenter);
+ * ```
+ */
+declare function decorate<T, C, P extends Presenter<T, C>>(data: T, PresenterClass: PresenterConstructor<T, C, P>, context?: C, options?: PresentOptions): P & T;
+/** Functional equivalent of `presentMany`. */
+declare function decorateMany<T, C, P extends Presenter<T, C>>(dataList: readonly T[], PresenterClass: PresenterConstructor<T, C, P>, context?: C, options?: PresentOptions): Array<P & T>;
+
+/**
+ * Wire up your app's i18n library / default locale / formatter overrides
+ * once, e.g. in a root layout or app entry point:
+ *
+ * ```ts
+ * configurePresenter({
+ *   translate: (key, params, locale) => i18next.t(key, { ...params, lng: locale }),
+ *   locale: "en-US",
+ * });
+ * ```
+ */
+declare function configurePresenter(config: PresenterGlobalConfig): void;
+declare function getPresenterConfig(): PresenterGlobalConfig;
+
+/**
+ * Build a locale-aware formatter. Presenters call this via `this.format`,
+ * automatically passing `context.locale` — you rarely need to call it
+ * directly.
+ */
+declare function createFormatAdapter(locale?: string): FormatAdapter;
+
+export { type AnyRecord, type FormatAdapter, type PresentOptions, Presenter, type PresenterConstructor, type PresenterGlobalConfig, type ToJSONOptions, type TranslateFn, configurePresenter, createFormatAdapter, decorate, decorateMany, getPresenterConfig };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+type AnyRecord = Record<string, unknown>;
+/**
+ * Shape tsc needs to accept a presenter class as a value (e.g. in
+ * `decorate(data, UserPresenter)` or `usePresenter(UserPresenter, data)`),
+ * so `T`/`C`/`P` can be inferred from the class that's passed in.
+ */
+interface PresenterConstructor<T, C, P> {
+    new (data: T, context?: C): P;
+}
+/**
+ * Extract a presenter's `data` type from the presenter type itself. Used
+ * so that `SomePresenter.present(data, context)` infers `T`/`C` from the
+ * concrete subclass (`this`) rather than independently from whatever gets
+ * passed at the call site — which is what lets a partial context object
+ * literal type-check against the presenter's declared context type.
+ */
+type DataOf<P> = P extends {
+    data: infer T;
+} ? T : never;
+type ContextOf<P> = P extends {
+    context: infer C;
+} ? C : never;
+interface PresentOptions {
+    /**
+     * Cache each getter's return value the first time it's read on a given
+     * presenter instance. Useful when a computed getter is expensive (e.g.
+     * heavy formatting or derived aggregation) and may be read more than
+     * once during a render. Off by default because most getters are cheap
+     * and memoizing can hide the fact that `data` changed underneath you.
+     */
+    memoize?: boolean;
+}
+interface ToJSONOptions {
+    /** Only include these presenter properties, in the given order. */
+    only?: readonly string[];
+    /** Include every presenter property except these. */
+    except?: readonly string[];
+}
+interface FormatAdapter {
+    date(value: Date | string | number, options?: Intl.DateTimeFormatOptions): string;
+    number(value: number, options?: Intl.NumberFormatOptions): string;
+    currency(value: number, currency?: string, options?: Intl.NumberFormatOptions): string;
+    relativeTime(value: Date | string | number, unit?: Intl.RelativeTimeFormatUnit): string;
+}
+type TranslateFn = (key: string, params?: AnyRecord, locale?: string) => string;
+interface PresenterGlobalConfig {
+    /** Plug in your i18n library (i18next, next-intl, FormatJS, ...) here. */
+    translate?: TranslateFn;
+    /** Fallback locale used when a presenter's context has none. */
+    locale?: string;
+    /** Override individual Intl-backed formatters globally. */
+    formatters?: Partial<FormatAdapter>;
+}
+
+/**
+ * Base class for all presenters/decorators.
+ *
+ * ```ts
+ * class ProductPresenter extends Presenter<Product> {
+ *   get isNew() {
+ *     const days = (Date.now() - new Date(this.data.created_at).getTime()) / 86_400_000;
+ *     return days <= 7;
+ *   }
+ * }
+ *
+ * const product = ProductPresenter.present(rawProduct);
+ * product.isNew;        // presenter getter
+ * product.seller;       // passed through from rawProduct automatically
+ * ```
+ */
+declare abstract class Presenter<T, C = AnyRecord> {
+    readonly data: T;
+    readonly context: C;
+    constructor(data: T, context?: C);
+    /**
+     * Intl-backed date/number/currency/relative-time formatting, aware of
+     * `context.locale`. Override globally via `configurePresenter`.
+     */
+    protected get format(): FormatAdapter;
+    /**
+     * Translate a key via the globally configured `translate` function
+     * (wire up i18next / next-intl / FormatJS / etc. once with
+     * `configurePresenter({ translate })`). Falls back to returning the key
+     * itself if nothing is configured, so it's always safe to call.
+     */
+    protected t(key: string, params?: AnyRecord): string;
+    /**
+     * Instantiate a presenter for a single entity and wrap it in a Proxy so
+     * every raw attribute not shadowed by a getter passes through
+     * automatically.
+     */
+    static present<P extends Presenter<any, any>>(this: new (data: DataOf<P>, context?: ContextOf<P>) => P, data: DataOf<P>, context?: ContextOf<P>, options?: PresentOptions): P & DataOf<P>;
+    /** Present a collection: `UserPresenter.presentMany(rawUsers)`. */
+    static presentMany<P extends Presenter<any, any>>(this: new (data: DataOf<P>, context?: ContextOf<P>) => P, dataList: readonly DataOf<P>[], context?: ContextOf<P>, options?: PresentOptions): Array<P & DataOf<P>>;
+    /**
+     * Resolve every async computed property and merge it with the sync
+     * getters into a single plain, JSON-serializable object.
+     *
+     * JavaScript has no `async get` syntax, so async computed properties are
+     * plain `async` methods instead:
+     *
+     * ```ts
+     * class UserPresenter extends Presenter<User> {
+     *   async profileScore() {
+     *     return calculateScore(this.data);
+     *   }
+     * }
+     *
+     * const resolved = await UserPresenter.present(user).resolve();
+     * resolved.profileScore; // number
+     * ```
+     *
+     * `resolve()` auto-detects any `async` method on the presenter — no
+     * extra registration needed — calls each with no arguments, and merges
+     * the results with `toJSON()`. A rejected async property resolves to
+     * `undefined` rather than failing the whole call.
+     */
+    resolve(this: Presenter<T, C>, options?: ToJSONOptions): Promise<Record<string, unknown>>;
+    /**
+     * Serialize the presenter's own computed getters (never the raw
+     * `data`/`context`) to a plain object. Safe to return from a Next.js
+     * Server Action or pass as props to a Client Component.
+     */
+    toJSON(options?: ToJSONOptions): Record<string, unknown>;
+    /** `presenter.only("id", "fullName", "avatarUrl")` */
+    only(...keys: string[]): Record<string, unknown>;
+    /** `presenter.except("internalNotes")` */
+    except(...keys: string[]): Record<string, unknown>;
+}
+
+/**
+ * Functional, Rails-`decorate`-style alternative to `Presenter.present`:
+ *
+ * ```ts
+ * import { decorate } from "react-presenter";
+ * const user = decorate(rawUser, UserPresenter);
+ * ```
+ */
+declare function decorate<T, C, P extends Presenter<T, C>>(data: T, PresenterClass: PresenterConstructor<T, C, P>, context?: C, options?: PresentOptions): P & T;
+/** Functional equivalent of `presentMany`. */
+declare function decorateMany<T, C, P extends Presenter<T, C>>(dataList: readonly T[], PresenterClass: PresenterConstructor<T, C, P>, context?: C, options?: PresentOptions): Array<P & T>;
+
+/**
+ * Wire up your app's i18n library / default locale / formatter overrides
+ * once, e.g. in a root layout or app entry point:
+ *
+ * ```ts
+ * configurePresenter({
+ *   translate: (key, params, locale) => i18next.t(key, { ...params, lng: locale }),
+ *   locale: "en-US",
+ * });
+ * ```
+ */
+declare function configurePresenter(config: PresenterGlobalConfig): void;
+declare function getPresenterConfig(): PresenterGlobalConfig;
+
+/**
+ * Build a locale-aware formatter. Presenters call this via `this.format`,
+ * automatically passing `context.locale` — you rarely need to call it
+ * directly.
+ */
+declare function createFormatAdapter(locale?: string): FormatAdapter;
+
+export { type AnyRecord, type FormatAdapter, type PresentOptions, Presenter, type PresenterConstructor, type PresenterGlobalConfig, type ToJSONOptions, type TranslateFn, configurePresenter, createFormatAdapter, decorate, decorateMany, getPresenterConfig };