@arcgis/toolkit 5.0.0-next.4 → 5.0.0-next.42

package/dist/log/index.cjs

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const loggedMessages = /* @__PURE__ */ new Set();
+let esriConfig;
+const setEsriConfig = (config) => {
+  esriConfig = config;
+};
+const getContextString = (context) => {
+  if (typeof context === "string") {
+    return context;
+  }
+  if ("el" in context) {
+    return context.el.localName;
+  }
+  if ("localName" in context) {
+    return context.localName;
+  }
+  return context.declaredClass;
+};
+const log = (level, context, message, options) => {
+  const contextString = getContextString(context);
+  if (options?.once) {
+    const key = `${level}${contextString}${message}`;
+    if (loggedMessages.has(key)) {
+      return;
+    }
+    loggedMessages.add(key);
+  }
+  esriConfig?.log.interceptors?.forEach((interceptor) => interceptor(level, contextString, message));
+  console[level](`[${contextString}]`, message);
+};
+const composeMissingPropertyMessage = (property) => (
+  //#endregion composeMissingPropertyMessage
+  `The property \`${property.toString()}\` is required but missing.`
+);
+const composeEmptyPropertyMessage = (property) => (
+  //#endregion composeEmptyPropertyMessage
+  `The property \`${property.toString()}\` is empty but must have at least one element.`
+);
+const logDeprecatedProperty = (context, oldName, newName, options) => (
+  //#endregion logDeprecatedProperty
+  log("warn", context, `\`${oldName.toString()}\` is deprecated. Use \`${newName.toString()}\` instead.`, options)
+);
+exports.composeEmptyPropertyMessage = composeEmptyPropertyMessage;
+exports.composeMissingPropertyMessage = composeMissingPropertyMessage;
+exports.log = log;
+exports.logDeprecatedProperty = logDeprecatedProperty;
+exports.setEsriConfig = setEsriConfig;

package/dist/log/index.d.cts

@@ -0,0 +1,94 @@
+export type LogLevel = "error" | "info" | "warn";
+type CustomElementLike = {
+    el: {
+        localName: string;
+    };
+} | {
+    localName: string;
+};
+type AccessorLike = {
+    declaredClass: string;
+};
+export type LogContext = AccessorLike | CustomElementLike | string;
+type LogOptions = {
+    /** Whether the message should only be logged once */
+    once?: boolean;
+};
+type EsriConfig = {
+    log: {
+        /**
+         * @link {https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#LogInterceptor}
+         */
+        interceptors?: ((level: LogLevel | "none", module: string, ...args: any[]) => void)[];
+    };
+};
+/**
+ * Workaround for setting {@link https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#log log interceptors} and maintaining compatibility with {@link https://devtopia.esri.com/WebGIS/arcgis-websceneviewer-app/blob/8f0a1bbcf12d1193134d94589d9e187f0afa72fa/src/js/support/ApiLoggerInstrumentation.ts#L17 js-api's interceptor usage}.
+ * @see {@link https://devtopia.esri.com/WebGIS/arcgis-js-api/discussions/74935}
+ * @param config {@link https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html}
+ * @example
+ * ```ts
+ * // IMPORTANT: do this only in config.ts or another early-loaded module
+ * import esriConfig from "@arcgis/core/config.js";
+ * import { setEsriConfig } from "@arcgis/toolkit/log";
+ *
+ * setEsriConfig(esriConfig);
+ *
+ * // either here or in another file, you can add your interceptors
+ * // and they will be respected when log is called later on
+ * esriConfig.log.interceptors?.push(yourInterceptor);
+ * ```
+ */
+export declare const setEsriConfig: (config: EsriConfig) => void;
+/**
+ * Helper utility for logging messages in a consistent manner.
+ *
+ * @see [setEsriConfig](#setEsriConfig)
+ *
+ * @example
+ * ```ts
+ * log("error", this, "message to log",
+ *   {
+ *     once: true, // only log this message once
+ *   }
+ * );
+ * ```
+ */
+export declare const log: (level: LogLevel, context: LogContext, message: unknown, options?: LogOptions) => void;
+type LogContextOrObject = Exclude<LogContext, string> | object;
+type InferPropertyType<T extends LogContextOrObject> = [object] extends [T] ? string : keyof T;
+/**
+ * Returns a string that can be used in log messages for missing required properties.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is required but missing."
+ * composeMissingPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeMissingPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeMissingPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Returns a string that can be used in log messages for empty required arrays.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is empty but must have at least one element."
+ * composeEmptyPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeEmptyPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeEmptyPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Logs a warning message for deprecated object properties.
+ * @example
+ * ```ts
+ * logDeprecatedProperty(this, "oldName", "newName", {
+ *   once: true,
+ * });
+ * ```
+ */
+export declare const logDeprecatedProperty: <T extends LogContext>(context: T, oldName: keyof T, newName: keyof T, options?: LogOptions) => ReturnType<typeof log>;
+export {};

package/dist/log/index.d.ts

@@ -0,0 +1,94 @@
+export type LogLevel = "error" | "info" | "warn";
+type CustomElementLike = {
+    el: {
+        localName: string;
+    };
+} | {
+    localName: string;
+};
+type AccessorLike = {
+    declaredClass: string;
+};
+export type LogContext = AccessorLike | CustomElementLike | string;
+type LogOptions = {
+    /** Whether the message should only be logged once */
+    once?: boolean;
+};
+type EsriConfig = {
+    log: {
+        /**
+         * @link {https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#LogInterceptor}
+         */
+        interceptors?: ((level: LogLevel | "none", module: string, ...args: any[]) => void)[];
+    };
+};
+/**
+ * Workaround for setting {@link https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#log log interceptors} and maintaining compatibility with {@link https://devtopia.esri.com/WebGIS/arcgis-websceneviewer-app/blob/8f0a1bbcf12d1193134d94589d9e187f0afa72fa/src/js/support/ApiLoggerInstrumentation.ts#L17 js-api's interceptor usage}.
+ * @see {@link https://devtopia.esri.com/WebGIS/arcgis-js-api/discussions/74935}
+ * @param config {@link https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html}
+ * @example
+ * ```ts
+ * // IMPORTANT: do this only in config.ts or another early-loaded module
+ * import esriConfig from "@arcgis/core/config.js";
+ * import { setEsriConfig } from "@arcgis/toolkit/log";
+ *
+ * setEsriConfig(esriConfig);
+ *
+ * // either here or in another file, you can add your interceptors
+ * // and they will be respected when log is called later on
+ * esriConfig.log.interceptors?.push(yourInterceptor);
+ * ```
+ */
+export declare const setEsriConfig: (config: EsriConfig) => void;
+/**
+ * Helper utility for logging messages in a consistent manner.
+ *
+ * @see [setEsriConfig](#setEsriConfig)
+ *
+ * @example
+ * ```ts
+ * log("error", this, "message to log",
+ *   {
+ *     once: true, // only log this message once
+ *   }
+ * );
+ * ```
+ */
+export declare const log: (level: LogLevel, context: LogContext, message: unknown, options?: LogOptions) => void;
+type LogContextOrObject = Exclude<LogContext, string> | object;
+type InferPropertyType<T extends LogContextOrObject> = [object] extends [T] ? string : keyof T;
+/**
+ * Returns a string that can be used in log messages for missing required properties.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is required but missing."
+ * composeMissingPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeMissingPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeMissingPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Returns a string that can be used in log messages for empty required arrays.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is empty but must have at least one element."
+ * composeEmptyPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeEmptyPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeEmptyPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Logs a warning message for deprecated object properties.
+ * @example
+ * ```ts
+ * logDeprecatedProperty(this, "oldName", "newName", {
+ *   once: true,
+ * });
+ * ```
+ */
+export declare const logDeprecatedProperty: <T extends LogContext>(context: T, oldName: keyof T, newName: keyof T, options?: LogOptions) => ReturnType<typeof log>;
+export {};

package/dist/log/index.js

@@ -0,0 +1,48 @@
+const loggedMessages = /* @__PURE__ */ new Set();
+let esriConfig;
+const setEsriConfig = (config) => {
+  esriConfig = config;
+};
+const getContextString = (context) => {
+  if (typeof context === "string") {
+    return context;
+  }
+  if ("el" in context) {
+    return context.el.localName;
+  }
+  if ("localName" in context) {
+    return context.localName;
+  }
+  return context.declaredClass;
+};
+const log = (level, context, message, options) => {
+  const contextString = getContextString(context);
+  if (options?.once) {
+    const key = `${level}${contextString}${message}`;
+    if (loggedMessages.has(key)) {
+      return;
+    }
+    loggedMessages.add(key);
+  }
+  esriConfig?.log.interceptors?.forEach((interceptor) => interceptor(level, contextString, message));
+  console[level](`[${contextString}]`, message);
+};
+const composeMissingPropertyMessage = (property) => (
+  //#endregion composeMissingPropertyMessage
+  `The property \`${property.toString()}\` is required but missing.`
+);
+const composeEmptyPropertyMessage = (property) => (
+  //#endregion composeEmptyPropertyMessage
+  `The property \`${property.toString()}\` is empty but must have at least one element.`
+);
+const logDeprecatedProperty = (context, oldName, newName, options) => (
+  //#endregion logDeprecatedProperty
+  log("warn", context, `\`${oldName.toString()}\` is deprecated. Use \`${newName.toString()}\` instead.`, options)
+);
+export {
+  composeEmptyPropertyMessage,
+  composeMissingPropertyMessage,
+  log,
+  logDeprecatedProperty,
+  setEsriConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/toolkit",
-  "version": "5.0.0-next.4",
+  "version": "5.0.0-next.42",
   "description": "Collection of common internal patterns and utilities for ArcGIS Maps SDK for JavaScript components.",
   "homepage": "https://developers.arcgis.com/javascript/latest/",
   "sideEffects": false,
@@ -31,6 +31,11 @@
       "import": "./dist/intl/index.js",
       "require": "./dist/intl/index.cjs"
     },
+    "./log": {
+      "types": "./dist/log/index.d.ts",
+      "import": "./dist/log/index.js",
+      "require": "./dist/log/index.cjs"
+    },
     "./number": {
       "types": "./dist/number/index.d.ts",
       "import": "./dist/number/index.js",