@arcgis/toolkit 5.0.0-next.3 → 5.0.0-next.30

package/dist/log/index.cjs

@@ -0,0 +1,47 @@
+"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 logIfMissingProperty = (level, context, property, options) => {
+  const value = context[property];
+  if (Array.isArray(value) && !value.length) {
+    return log(level, context, `The \`${property.toString()}\` property must have at least one element.`, options);
+  } else if (value == null) {
+    return log(level, context, `The \`${property.toString()}\` property is required but missing.`, options);
+  }
+};
+const logDeprecatedProperty = (context, oldName, newName, options) => (
+  //#endregion logDeprecatedProperty
+  log("warn", context, `\`${oldName.toString()}\` is deprecated. Use \`${newName.toString()}\` instead.`, options)
+);
+exports.log = log;
+exports.logDeprecatedProperty = logDeprecatedProperty;
+exports.logIfMissingProperty = logIfMissingProperty;
+exports.setEsriConfig = setEsriConfig;

package/dist/log/index.d.cts

@@ -0,0 +1,79 @@
+type LogLevel = "error" | "info" | "warn";
+type CustomElementLike = {
+    el: {
+        localName: string;
+    };
+} | {
+    localName: string;
+};
+type AccessorLike = {
+    declaredClass: string;
+};
+type ErrorContext = AccessorLike | CustomElementLike | string;
+export type Logger = (level: LogLevel, context: ErrorContext, message: unknown, options: LoggerOptions) => void;
+type LoggerOptions = {
+    /** 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: Logger;
+/**
+ * Logs a message if a required property of the given context object is nullish (or an empty array).
+ * @param property The missing property to check for
+ * @param params Parameters to forward to the logger
+ * @example
+ * ```ts
+ * logIfMissingProperty<typeof this>("warn", this, "items", { once: true });
+ * ```
+ */
+export declare const logIfMissingProperty: <T extends ErrorContext>(level: LogLevel, context: T, property: keyof T, options: LoggerOptions) => ReturnType<typeof log>;
+/**
+ * Logs a warning message for deprecated object properties.
+ * @example
+ * ```ts
+ * logDeprecatedProperty(this, "oldName", "newName", {
+ *   once: true,
+ * });
+ * ```
+ */
+export declare const logDeprecatedProperty: <T extends ErrorContext>(context: T, oldName: keyof T, newName: keyof T, options: LoggerOptions) => ReturnType<typeof log>;
+export {};

package/dist/log/index.d.ts

@@ -0,0 +1,79 @@
+type LogLevel = "error" | "info" | "warn";
+type CustomElementLike = {
+    el: {
+        localName: string;
+    };
+} | {
+    localName: string;
+};
+type AccessorLike = {
+    declaredClass: string;
+};
+type ErrorContext = AccessorLike | CustomElementLike | string;
+export type Logger = (level: LogLevel, context: ErrorContext, message: unknown, options: LoggerOptions) => void;
+type LoggerOptions = {
+    /** 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: Logger;
+/**
+ * Logs a message if a required property of the given context object is nullish (or an empty array).
+ * @param property The missing property to check for
+ * @param params Parameters to forward to the logger
+ * @example
+ * ```ts
+ * logIfMissingProperty<typeof this>("warn", this, "items", { once: true });
+ * ```
+ */
+export declare const logIfMissingProperty: <T extends ErrorContext>(level: LogLevel, context: T, property: keyof T, options: LoggerOptions) => ReturnType<typeof log>;
+/**
+ * Logs a warning message for deprecated object properties.
+ * @example
+ * ```ts
+ * logDeprecatedProperty(this, "oldName", "newName", {
+ *   once: true,
+ * });
+ * ```
+ */
+export declare const logDeprecatedProperty: <T extends ErrorContext>(context: T, oldName: keyof T, newName: keyof T, options: LoggerOptions) => ReturnType<typeof log>;
+export {};

package/dist/log/index.js

@@ -0,0 +1,47 @@
+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 logIfMissingProperty = (level, context, property, options) => {
+  const value = context[property];
+  if (Array.isArray(value) && !value.length) {
+    return log(level, context, `The \`${property.toString()}\` property must have at least one element.`, options);
+  } else if (value == null) {
+    return log(level, context, `The \`${property.toString()}\` property is required but missing.`, options);
+  }
+};
+const logDeprecatedProperty = (context, oldName, newName, options) => (
+  //#endregion logDeprecatedProperty
+  log("warn", context, `\`${oldName.toString()}\` is deprecated. Use \`${newName.toString()}\` instead.`, options)
+);
+export {
+  log,
+  logDeprecatedProperty,
+  logIfMissingProperty,
+  setEsriConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/toolkit",
-  "version": "5.0.0-next.3",
+  "version": "5.0.0-next.30",
   "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",