@objectstack/core 9.8.0 → 9.9.1

package/dist/index.d.cts

@@ -1741,6 +1741,40 @@ declare function getMemoryUsage(): {
     heapTotal: number;
 };
 
+/**
+ * Timezone-aware calendar utilities (ADR-0053 Phase 2).
+ *
+ * The one primitive everything else builds on is {@link calendarPartsInTz}:
+ * the year/month/day an instant falls on *as seen in a reference timezone*.
+ * It uses `Intl.DateTimeFormat().formatToParts()` so DST transitions are
+ * handled by the platform's tz database — never hand-rolled offset math, which
+ * is the classic source of off-by-one-hour bucket errors.
+ *
+ * This lives in `@objectstack/core` (not `@objectstack/formula`) because both
+ * the ObjectQL aggregation engine and the analytics service need it and both
+ * already depend on core, whereas neither depends on formula's public surface.
+ * (`@objectstack/formula` keeps its own private copy for `today()`/`daysFromNow`
+ * to avoid a layering dependency on core.)
+ */
+/** Calendar-day parts in a reference timezone. `month` is 1-12. */
+interface CalendarParts {
+    year: number;
+    month: number;
+    day: number;
+}
+/**
+ * The year/month/day an instant falls on in `tz`. Throws if `tz` is not a
+ * valid IANA zone (callers treat that as a fall-through to UTC).
+ */
+declare function calendarPartsInTz(d: Date, tz: string): CalendarParts;
+/**
+ * The calendar-day parts of an instant, in `tz` when it's a real non-UTC zone,
+ * otherwise in UTC. Never throws: an unset, `'UTC'`, or invalid zone falls back
+ * to the UTC calendar day. This is the safe entry point for bucketing code that
+ * must degrade to the historical UTC behavior rather than error.
+ */
+declare function calendarPartsInTzOrUtc(d: Date, tz?: string): CalendarParts;
+
 /**
  * In-memory Map-backed cache fallback.
  *
@@ -2133,4 +2167,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };
+export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };

package/dist/index.d.ts

@@ -1741,6 +1741,40 @@ declare function getMemoryUsage(): {
     heapTotal: number;
 };
 
+/**
+ * Timezone-aware calendar utilities (ADR-0053 Phase 2).
+ *
+ * The one primitive everything else builds on is {@link calendarPartsInTz}:
+ * the year/month/day an instant falls on *as seen in a reference timezone*.
+ * It uses `Intl.DateTimeFormat().formatToParts()` so DST transitions are
+ * handled by the platform's tz database — never hand-rolled offset math, which
+ * is the classic source of off-by-one-hour bucket errors.
+ *
+ * This lives in `@objectstack/core` (not `@objectstack/formula`) because both
+ * the ObjectQL aggregation engine and the analytics service need it and both
+ * already depend on core, whereas neither depends on formula's public surface.
+ * (`@objectstack/formula` keeps its own private copy for `today()`/`daysFromNow`
+ * to avoid a layering dependency on core.)
+ */
+/** Calendar-day parts in a reference timezone. `month` is 1-12. */
+interface CalendarParts {
+    year: number;
+    month: number;
+    day: number;
+}
+/**
+ * The year/month/day an instant falls on in `tz`. Throws if `tz` is not a
+ * valid IANA zone (callers treat that as a fall-through to UTC).
+ */
+declare function calendarPartsInTz(d: Date, tz: string): CalendarParts;
+/**
+ * The calendar-day parts of an instant, in `tz` when it's a real non-UTC zone,
+ * otherwise in UTC. Never throws: an unset, `'UTC'`, or invalid zone falls back
+ * to the UTC calendar day. This is the safe entry point for bucketing code that
+ * must degrade to the historical UTC behavior rather than error.
+ */
+declare function calendarPartsInTzOrUtc(d: Date, tz?: string): CalendarParts;
+
 /**
  * In-memory Map-backed cache fallback.
  *
@@ -2133,4 +2167,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };
+export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResourceUsage, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isExpired, isNode, parseScopes, parseSignature, resolveApiKeyPrincipal, resolveLocale, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature };

package/dist/index.js

@@ -3987,6 +3987,31 @@ function safeJsonParse(s, fallback) {
   }
 }
 
+// src/utils/datetime.ts
+function calendarPartsInTz(d, tz) {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(d);
+  const get = (t) => Number(parts.find((p) => p.type === t)?.value);
+  return { year: get("year"), month: get("month"), day: get("day") };
+}
+function calendarPartsInTzOrUtc(d, tz) {
+  if (tz && tz !== "UTC") {
+    try {
+      return calendarPartsInTz(d, tz);
+    } catch {
+    }
+  }
+  return {
+    year: d.getUTCFullYear(),
+    month: d.getUTCMonth() + 1,
+    day: d.getUTCDate()
+  };
+}
+
 // src/health-monitor.ts
 var PluginHealthMonitor = class {
   constructor(logger) {
@@ -4925,6 +4950,8 @@ export {
   SemanticVersionManager,
   ServiceLifecycle,
   buildPermissionsFromGrants,
+  calendarPartsInTz,
+  calendarPartsInTzOrUtc,
   counterSignPayload,
   createApiRegistryPlugin,
   createLogger,