@objectstack/types 7.1.0 → 7.2.1

package/dist/index.d.mts

@@ -1,3 +1,31 @@
+/**
+ * Read an env var, preferring the canonical `OS_*` name and falling
+ * back to one or more legacy aliases.
+ *
+ * When only a legacy alias is set, emits a one-shot deprecation warning.
+ * The warning is process-wide deduplicated: identical (preferred, legacy)
+ * pairs will only warn once even if read from multiple call sites.
+ *
+ * Legacy aliases are checked in order; the first one with a defined
+ * value wins (and triggers the warning for that specific alias).
+ *
+ * Safe to call from environments where `process` is unavailable (returns
+ * `undefined`); the warning is suppressed when running outside Node-like
+ * runtimes that lack `console.warn`.
+ *
+ * @param preferred  Canonical OS_*-prefixed env var name.
+ * @param legacy     Older name (or array of older names) to fall back on.
+ * @returns The resolved value, or `undefined` if neither is set.
+ */
+declare function readEnvWithDeprecation(preferred: string, legacy: string | readonly string[]): string | undefined;
+/**
+ * Internal: clear the dedupe set. Test-only; exposed so suite-wide
+ * deprecation warnings don't bleed between tests.
+ *
+ * @internal
+ */
+declare function _resetEnvDeprecationWarnings(): void;
+
 interface IKernel {
     ql?: any;
     start(): Promise<void>;
@@ -12,4 +40,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export type { IKernel, RuntimeContext, RuntimePlugin };
+export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, readEnvWithDeprecation };

package/dist/index.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Read an env var, preferring the canonical `OS_*` name and falling
+ * back to one or more legacy aliases.
+ *
+ * When only a legacy alias is set, emits a one-shot deprecation warning.
+ * The warning is process-wide deduplicated: identical (preferred, legacy)
+ * pairs will only warn once even if read from multiple call sites.
+ *
+ * Legacy aliases are checked in order; the first one with a defined
+ * value wins (and triggers the warning for that specific alias).
+ *
+ * Safe to call from environments where `process` is unavailable (returns
+ * `undefined`); the warning is suppressed when running outside Node-like
+ * runtimes that lack `console.warn`.
+ *
+ * @param preferred  Canonical OS_*-prefixed env var name.
+ * @param legacy     Older name (or array of older names) to fall back on.
+ * @returns The resolved value, or `undefined` if neither is set.
+ */
+declare function readEnvWithDeprecation(preferred: string, legacy: string | readonly string[]): string | undefined;
+/**
+ * Internal: clear the dedupe set. Test-only; exposed so suite-wide
+ * deprecation warnings don't bleed between tests.
+ *
+ * @internal
+ */
+declare function _resetEnvDeprecationWarnings(): void;
+
 interface IKernel {
     ql?: any;
     start(): Promise<void>;
@@ -12,4 +40,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export type { IKernel, RuntimeContext, RuntimePlugin };
+export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, readEnvWithDeprecation };

package/dist/index.js

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -15,5 +19,45 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  _resetEnvDeprecationWarnings: () => _resetEnvDeprecationWarnings,
+  readEnvWithDeprecation: () => readEnvWithDeprecation
+});
 module.exports = __toCommonJS(index_exports);
+
+// src/env.ts
+var _warnedKeys = /* @__PURE__ */ new Set();
+function readEnvWithDeprecation(preferred, legacy) {
+  const env = globalThis.process?.env;
+  if (!env) return void 0;
+  const preferredValue = env[preferred];
+  if (preferredValue !== void 0) return preferredValue;
+  const legacyList = typeof legacy === "string" ? [legacy] : legacy;
+  for (const legacyName of legacyList) {
+    const legacyValue = env[legacyName];
+    if (legacyValue !== void 0) {
+      const dedupeKey = `${preferred}|${legacyName}`;
+      if (!_warnedKeys.has(dedupeKey)) {
+        _warnedKeys.add(dedupeKey);
+        const consoleRef = globalThis.console;
+        try {
+          consoleRef?.warn?.(
+            `[ObjectStack] Env var \`${legacyName}\` is deprecated; rename it to \`${preferred}\`. The legacy name still works for now but will be removed in a future major release.`
+          );
+        } catch {
+        }
+      }
+      return legacyValue;
+    }
+  }
+  return void 0;
+}
+function _resetEnvDeprecationWarnings() {
+  _warnedKeys.clear();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  _resetEnvDeprecationWarnings,
+  readEnvWithDeprecation
+});
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n// Placeholder for Kernel interface to avoid circular dependency\n// The actual Kernel implementation will satisfy this interface.\nexport interface IKernel {\n    // We can add specific methods here that plugins are allowed to call\n    // forcing a stricter contract than exposing the whole class.\n    ql?: any; // ObjectQL instance (optional to support initialization phase)\n    start(): Promise<void>;\n    // ... expose other needed public methods\n    [key: string]: any; \n}\n\nexport interface RuntimeContext {\n    engine: IKernel;\n}\n\nexport interface RuntimePlugin {\n    name: string;\n    install?: (ctx: RuntimeContext) => void | Promise<void>;\n    onStart?: (ctx: RuntimeContext) => void | Promise<void>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport * from './env.js';\n\n// Placeholder for Kernel interface to avoid circular dependency\n// The actual Kernel implementation will satisfy this interface.\nexport interface IKernel {\n    // We can add specific methods here that plugins are allowed to call\n    // forcing a stricter contract than exposing the whole class.\n    ql?: any; // ObjectQL instance (optional to support initialization phase)\n    start(): Promise<void>;\n    // ... expose other needed public methods\n    [key: string]: any; \n}\n\nexport interface RuntimeContext {\n    engine: IKernel;\n}\n\nexport interface RuntimePlugin {\n    name: string;\n    install?: (ctx: RuntimeContext) => void | Promise<void>;\n    onStart?: (ctx: RuntimeContext) => void | Promise<void>;\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBA,IAAM,cAAc,oBAAI,IAAY;AAqB7B,SAAS,uBACd,WACA,QACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,YAAY,IAAI,SAAS,GAAG;AAC/B,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}

package/dist/index.mjs

@@ -1 +1,35 @@
+// src/env.ts
+var _warnedKeys = /* @__PURE__ */ new Set();
+function readEnvWithDeprecation(preferred, legacy) {
+  const env = globalThis.process?.env;
+  if (!env) return void 0;
+  const preferredValue = env[preferred];
+  if (preferredValue !== void 0) return preferredValue;
+  const legacyList = typeof legacy === "string" ? [legacy] : legacy;
+  for (const legacyName of legacyList) {
+    const legacyValue = env[legacyName];
+    if (legacyValue !== void 0) {
+      const dedupeKey = `${preferred}|${legacyName}`;
+      if (!_warnedKeys.has(dedupeKey)) {
+        _warnedKeys.add(dedupeKey);
+        const consoleRef = globalThis.console;
+        try {
+          consoleRef?.warn?.(
+            `[ObjectStack] Env var \`${legacyName}\` is deprecated; rename it to \`${preferred}\`. The legacy name still works for now but will be removed in a future major release.`
+          );
+        } catch {
+        }
+      }
+      return legacyValue;
+    }
+  }
+  return void 0;
+}
+function _resetEnvDeprecationWarnings() {
+  _warnedKeys.clear();
+}
+export {
+  _resetEnvDeprecationWarnings,
+  readEnvWithDeprecation
+};
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n"],"mappings":";AAmBA,IAAM,cAAc,oBAAI,IAAY;AAqB7B,SAAS,uBACd,WACA,QACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,YAAY,IAAI,SAAS,GAAG;AAC/B,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/types",
-  "version": "7.1.0",
+  "version": "7.2.1",
   "license": "Apache-2.0",
   "description": "Shared interfaces describing the ObjectStack Runtime environment",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "7.1.0"
+    "@objectstack/spec": "7.2.1"
   },
   "devDependencies": {
     "typescript": "^6.0.3"