ArcGIS Core Utilities

Use this skill for core infrastructure patterns like Accessor, Collection, reactive utilities, and workers.

Accessor Pattern

The Accessor class is the foundation for all ArcGIS classes, providing property watching and computed properties.

Creating Custom Accessor Classes

import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass("myapp.CustomClass")
class CustomClass extends Accessor {
  @property()
  name = "default";

  @property()
  value = 0;

  // Computed property
  @property({
    readOnly: true,
    dependsOn: ["name", "value"]
  })
  get summary() {
    return `${this.name}: ${this.value}`;
  }
}

const instance = new CustomClass({ name: "Test", value: 42 });
console.log(instance.summary); // "Test: 42"

Property Decorators

@subclass("myapp.MyClass")
class MyClass extends Accessor {
  // Basic property
  @property()
  title = "";

  // Property with type casting
  @property({ type: Number })
  count = 0;

  // Read-only computed property
  @property({ readOnly: true })
  get displayName() {
    return this.title.toUpperCase();
  }

  // Property with custom setter
  @property()
  get status() {
    return this._status;
  }
  set status(value) {
    this._status = value?.toLowerCase() || "unknown";
  }

  // Property that depends on others
  @property({
    readOnly: true,
    dependsOn: ["count", "title"]
  })
  get info() {
    return `${this.title} (${this.count})`;
  }
}

Property Types

@property({ type: String })
name = "";

@property({ type: Number })
count = 0;

@property({ type: Boolean })
enabled = true;

@property({ type: Date })
createdAt = new Date();

@property({ type: [Number] })  // Array of numbers
values = [];

@property({ type: SomeClass })  // Custom class
child = null;

Collection

Collection is an array-like class with change notifications.

Basic Usage

import Collection from "@arcgis/core/core/Collection.js";

const collection = new Collection([
  { id: 1, name: "Item 1" },
  { id: 2, name: "Item 2" }
]);

// Add items
collection.add({ id: 3, name: "Item 3" });
collection.addMany([
  { id: 4, name: "Item 4" },
  { id: 5, name: "Item 5" }
]);

// Remove items
collection.remove(item);
collection.removeAt(0);
collection.removeMany([item1, item2]);
collection.removeAll();

// Access items
const first = collection.getItemAt(0);
const all = collection.toArray();
const length = collection.length;

Collection Methods

// Find items
const found = collection.find(item => item.id === 3);
const index = collection.findIndex(item => item.name === "Item 2");
const filtered = collection.filter(item => item.value > 10);

// Transform
const mapped = collection.map(item => item.name);
const reduced = collection.reduce((acc, item) => acc + item.value, 0);

// Check
const hasItem = collection.includes(item);
const exists = collection.some(item => item.active);
const allActive = collection.every(item => item.active);

// Sort and reorder
collection.sort((a, b) => a.name.localeCompare(b.name));
collection.reverse();
collection.reorder(item, 0); // Move item to index 0

// Iterate
collection.forEach(item => console.log(item.name));
for (const item of collection) {
  console.log(item);
}

Collection Events

// Watch for changes
collection.on("change", (event) => {
  console.log("Added:", event.added);
  console.log("Removed:", event.removed);
  console.log("Moved:", event.moved);
});

// Watch length
collection.watch("length", (newLength, oldLength) => {
  console.log(`Length changed from ${oldLength} to ${newLength}`);
});

Typed Collections

// Collection of specific type
import Graphic from "@arcgis/core/Graphic.js";

const graphics = new Collection();
graphics.addMany([
  new Graphic({ geometry: point1 }),
  new Graphic({ geometry: point2 })
]);

// Map's layers is a Collection
map.layers.add(featureLayer);
map.layers.reorder(featureLayer, 0);

reactiveUtils

Modern reactive utilities for watching properties and state changes.

watch()

Watch a property for changes.

import reactiveUtils from "@arcgis/core/core/reactiveUtils.js";

// Watch single property
const handle = reactiveUtils.watch(
  () => view.scale,
  (scale) => {
    console.log("Scale changed to:", scale);
  }
);

// With options
reactiveUtils.watch(
  () => view.extent,
  (extent) => console.log("Extent:", extent),
  { initial: true }  // Call immediately with current value
);

// Stop watching
handle.remove();

when()

Wait for a condition to become true.

// Wait for view to be ready
await reactiveUtils.when(
  () => view.ready,
  () => console.log("View is ready!")
);

// Wait for layer to load
await reactiveUtils.when(
  () => layer.loaded
);
console.log("Layer loaded");

// With timeout (throws if not met)
await reactiveUtils.when(
  () => view.stationary,
  { timeout: 5000 }
);

once()

Watch for a value change only once.

// Execute once when condition is met
await reactiveUtils.once(
  () => view.ready
);
console.log("View became ready");

// Once with callback
reactiveUtils.once(
  () => layer.visible,
  (visible) => console.log("Layer visibility changed to:", visible)
);

whenOnce()

Deprecated - use when() or once() instead.

on()

Listen to events reactively.

// Listen to click events
const handle = reactiveUtils.on(
  () => view,
  "click",
  (event) => {
    console.log("Clicked at:", event.mapPoint);
  }
);

// Listen to layer view events
reactiveUtils.on(
  () => view.whenLayerView(layer),
  "highlight",
  (event) => console.log("Highlight changed")
);

Multiple Properties

// Watch multiple properties
reactiveUtils.watch(
  () => [view.center, view.zoom],
  ([center, zoom]) => {
    console.log(`Center: ${center.x}, ${center.y}, Zoom: ${zoom}`);
  }
);

// Computed expression
reactiveUtils.watch(
  () => view.scale < 50000,
  (isZoomedIn) => {
    layer.visible = isZoomedIn;
  }
);

Sync Option

// Synchronous updates (use carefully)
reactiveUtils.watch(
  () => view.extent,
  (extent) => updateUI(extent),
  { sync: true }
);

Handles

Manage multiple watch handles for cleanup.

import Handles from "@arcgis/core/core/Handles.js";

const handles = new Handles();

// Add handles
handles.add(
  reactiveUtils.watch(() => view.scale, (scale) => {})
);

handles.add(
  view.on("click", (e) => {}),
  "click-handlers"  // Group name
);

handles.add([
  reactiveUtils.watch(() => view.center, () => {}),
  reactiveUtils.watch(() => view.zoom, () => {})
], "view-watchers");

// Remove specific group
handles.remove("click-handlers");

// Remove all
handles.removeAll();

// Destroy (also removes all)
handles.destroy();

In Custom Classes

@subclass("myapp.MyWidget")
class MyWidget extends Accessor {
  constructor(props) {
    super(props);
    this.handles = new Handles();
  }

  initialize() {
    this.handles.add(
      reactiveUtils.watch(
        () => this.view?.scale,
        (scale) => this.onScaleChange(scale)
      )
    );
  }

  destroy() {
    this.handles.destroy();
    super.destroy();
  }
}

promiseUtils

Utilities for working with Promises.

import promiseUtils from "@arcgis/core/core/promiseUtils.js";

create()

Create an abortable promise.

const { promise, resolve, reject } = promiseUtils.create();

// Later...
resolve(result);
// or
reject(new Error("Failed"));

// Wait for it
const result = await promise;

eachAlways()

Wait for all promises, regardless of success/failure.

const results = await promiseUtils.eachAlways([
  fetch("/api/data1"),
  fetch("/api/data2"),
  fetch("/api/data3")
]);

results.forEach((result, index) => {
  if (result.error) {
    console.error(`Request ${index} failed:`, result.error);
  } else {
    console.log(`Request ${index} succeeded:`, result.value);
  }
});

debounce()

Debounce a function.

const debouncedSearch = promiseUtils.debounce(async (query) => {
  const results = await searchService.search(query);
  return results;
});

// Rapid calls will be debounced
input.addEventListener("input", async (e) => {
  try {
    const results = await debouncedSearch(e.target.value);
    displayResults(results);
  } catch (e) {
    if (!promiseUtils.isAbortError(e)) {
      console.error(e);
    }
  }
});

throttle()

Throttle a function.

const throttledUpdate = promiseUtils.throttle(async (extent) => {
  await updateDisplay(extent);
}, 100); // Max once per 100ms

view.watch("extent", throttledUpdate);

isAbortError()

Check if error is from aborted operation.

try {
  await someAsyncOperation();
} catch (error) {
  if (promiseUtils.isAbortError(error)) {
    console.log("Operation was cancelled");
  } else {
    throw error;
  }
}

timeout()

Add timeout to a promise.

try {
  const result = await promiseUtils.timeout(
    fetch("/api/slow-endpoint"),
    5000  // 5 second timeout
  );
} catch (e) {
  console.error("Request timed out or failed");
}

Workers

Run heavy computations in background threads.

import workers from "@arcgis/core/core/workers.js";

Open Worker Connection

const connection = await workers.open("path/to/worker.js");

// Execute method on worker
const result = await connection.invoke("methodName", { data: "params" });

// Close when done
connection.close();

Worker Script Example

// worker.js
define([], function() {
  return {
    methodName: function(params) {
      // Heavy computation here
      const result = processData(params.data);
      return result;
    },

    anotherMethod: function(params) {
      return params.value * 2;
    }
  };
});

Using Workers for Heavy Tasks

// Main script
import workers from "@arcgis/core/core/workers.js";

async function processLargeDataset(data) {
  const connection = await workers.open("./dataProcessor.js");

  try {
    const result = await connection.invoke("process", {
      data: data,
      options: { threshold: 100 }
    });
    return result;
  } finally {
    connection.close();
  }
}

Error Handling

import Error from "@arcgis/core/core/Error.js";

// Create custom error
const error = new Error("layer-load-error", "Failed to load layer", {
  layer: layer,
  originalError: e
});

// Check error type
if (error.name === "layer-load-error") {
  console.log("Layer failed:", error.details.layer.title);
}

URL Utilities

import urlUtils from "@arcgis/core/core/urlUtils.js";

// Add proxy rule
urlUtils.addProxyRule({
  urlPrefix: "https://services.arcgis.com",
  proxyUrl: "/proxy"
});

// Get proxy URL
const proxiedUrl = urlUtils.getProxyUrl("https://services.arcgis.com/data");

// URL helpers
const normalized = urlUtils.normalize("https://example.com//path//to//resource");

Units and Quantities

import units from "@arcgis/core/core/units.js";

// Convert units
const meters = units.convertUnit(100, "feet", "meters");
const sqKm = units.convertUnit(1000, "acres", "square-kilometers");

// Get unit info
const info = units.getUnitInfo("meters");
console.log(info.abbreviation); // "m"
console.log(info.pluralLabel); // "meters"

Scheduling

import scheduling from "@arcgis/core/core/scheduling.js";

// Schedule for next frame
const handle = scheduling.addFrameTask({
  update: (event) => {
    // Called every frame
    console.log("Delta time:", event.deltaTime);
    console.log("Elapsed:", event.elapsedTime);
  }
});

// Remove task
handle.remove();

// One-time frame callback
scheduling.schedule(() => {
  console.log("Executed on next frame");
});

Common Patterns

Cleanup Pattern

class MyComponent {
  constructor(view) {
    this.view = view;
    this.handles = new Handles();
    this.setup();
  }

  setup() {
    this.handles.add([
      reactiveUtils.watch(
        () => this.view.scale,
        (scale) => this.onScaleChange(scale)
      ),
      reactiveUtils.watch(
        () => this.view.extent,
        (extent) => this.onExtentChange(extent)
      ),
      this.view.on("click", (e) => this.onClick(e))
    ]);
  }

  destroy() {
    this.handles.removeAll();
  }
}

Debounced Updates

const debouncedUpdate = promiseUtils.debounce(async () => {
  const extent = view.extent;
  const results = await layer.queryFeatures({
    geometry: extent,
    returnGeometry: true
  });
  updateDisplay(results);
});

reactiveUtils.watch(
  () => view.stationary && view.extent,
  debouncedUpdate
);

Conditional Watching

// Only react when view is stationary
reactiveUtils.watch(
  () => view.stationary ? view.extent : null,
  (extent) => {
    if (extent) {
      updateForExtent(extent);
    }
  }
);

Common Pitfalls

1. Memory Leaks: Always remove handles when done

   // Store handle reference
   const handle = reactiveUtils.watch(...);
   // Remove when no longer needed
   handle.remove();
   

2. Initial Value: Use initial: true to get current value immediately

   reactiveUtils.watch(
     () => view.scale,
     (scale) => updateUI(scale),
     { initial: true }  // Called immediately with current scale
   );
   

3. Sync vs Async: Default is async batching, use sync: true carefully

   // Async (default) - batched, better performance
   reactiveUtils.watch(() => value, callback);
   
   // Sync - immediate, can cause performance issues
   reactiveUtils.watch(() => value, callback, { sync: true });
   

4. Abort Errors: Always check for abort errors in catch blocks

   try {
     await debouncedFunction();
   } catch (e) {
     if (!promiseUtils.isAbortError(e)) {
       throw e;
     }
   }