refactor!: Extract service management from Configuration into ServiceLocator class (#3325)

closes #3073

Author: janbuchar

docs/upgrading/upgrading_v4.md

@@ -40,6 +40,7 @@ The crawler following options are removed:
 
 - `BasicCrawler._cleanupContext` (protected) - this is now handled by the `ContextPipeline`
 - `BasicCrawler.isRequestBlocked` (protected)
+- `BasicCrawler.events` (protected) - this should be accessed via `BasicCrawler.serviceLocator`
 - `BrowserRequestHandler` and `BrowserErrorHandler` types in `@crawlee/browser`
 - `BrowserCrawler.userProvidedRequestHandler` (protected)
 - `BrowserCrawler.requestHandlerTimeoutInnerMillis` (protected)
@@ -115,6 +116,97 @@ The `KeyValueStore.getPublicUrl` method is now asynchronous and reads the public
 
 The `preNavigationHooks` option in `HttpCrawler` subclasses no longer accepts the `gotOptions` object as a second parameter. Modify the `crawlingContext` fields (e.g. `.request`) directly instead.
 
+## Service management moved from `Configuration` to `ServiceLocator`
+
+The service management functionality has been extracted from `Configuration` into a new `ServiceLocator` class, following the pattern established in Crawlee for Python.
+
+### Breaking changes
+
+The following methods and properties have been removed from `Configuration`:
+
+- `Configuration.getStorageClient()` - moved to `ServiceLocator.getStorageClient()`
+- `Configuration.getEventManager()` - moved to `ServiceLocator.getEventManager()`
+- `Configuration.useStorageClient()` - use `ServiceLocator.setStorageClient()` instead
+- `Configuration.useEventManager()` - use `ServiceLocator.setEventManager()` instead
+- `Configuration.storageManagers` - moved to `ServiceLocator.storageManagers`
+
+The `EventManager` and `LocalEventManager` constructors now accept an options object for configuring event intervals (e.g. `persistStateIntervalMillis`, `systemInfoIntervalMillis`). You can also use the new `LocalEventManager.fromConfig()` factory method to create an instance with intervals derived from a `Configuration` object.
+
+### Migration guide
+
+If you were using the removed `Configuration` methods directly, you need to update your code:
+
+**Before:**
+```typescript
+import { Configuration } from 'crawlee';
+
+const config = Configuration.getGlobalConfig();
+const storageClient = config.getStorageClient();
+const eventManager = config.getEventManager();
+
+// or static methods
+const storageClient = Configuration.getStorageClient();
+```
+
+**After:**
+```typescript
+import { serviceLocator } from 'crawlee';
+
+const storageClient = serviceLocator.getStorageClient();
+const eventManager = serviceLocator.getEventManager();
+```
+
+### Using per-crawler services (recommended)
+
+The new `ServiceLocator` supports per-crawler service isolation, allowing you to use different storage clients or event managers for different crawlers by passing them via options:
+
+```typescript
+import { BasicCrawler, Configuration, LocalEventManager } from 'crawlee';
+import { MemoryStorage } from '@crawlee/memory-storage';
+
+const crawler = new BasicCrawler({
+    requestHandler: async ({ request, log }) => {
+        log.info(`Processing ${request.url}`);
+    },
+    configuration: new Configuration({ headless: false }),
+    storageClient: new MemoryStorage(),
+    eventManager: LocalEventManager.fromConfig(),
+});
+
+await crawler.run(['https://example.com']);
+```
+
+### Using the global service locator
+
+For most use cases, the global `serviceLocator` singleton works well:
+
+```typescript
+import { serviceLocator, BasicCrawler } from 'crawlee';
+import { MemoryStorage } from '@crawlee/memory-storage';
+
+// Configure global services (optional)
+serviceLocator.setStorageClient(new MemoryStorage());
+
+// All crawlers will use the global service locator by default
+const crawler = new BasicCrawler({
+    requestHandler: async ({ request, log }) => {
+        log.info(`Processing ${request.url}`);
+    },
+});
+```
+
+### Accessing configuration
+
+`Configuration.getGlobalConfig()` remains as a utility function, but in most cases, you should use `serviceLocator.getConfiguration()` instead:
+
+```typescript
+import { serviceLocator } from 'crawlee';
+
+const config = serviceLocator.getConfiguration();
+```
+
+Do note that the method is currently misnamed - in specific circumstances, it will not return the global configuration object, but the one from the currently active service locator.
+
 ## `transformRequestFunction` precedence in `enqueueLinks`
 
 The `transformRequestFunction` callback in `enqueueLinks` now runs **after** URL pattern filtering (`globs`, `regexps`, `pseudoUrls`) instead of before. This means it has the highest priority and can overwrite any request options set by patterns or the global `label` option.