@wildo-ai/saas-frontend-lib 1.1.1 → 1.1.3

package/dist/esm/core/resources/resource-read-cache.frontend.service.js

@@ -0,0 +1,227 @@
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+const logger = LoggerFrontendService.getLogger();
+const logDebug = logger.debugByType('ResourceReadCache');
+logger.setDebugTypeLogging('ResourceReadCache', false);
+/**
+ * A ceiling on how many read results are held.
+ *
+ * Not a memory bound so much as a staleness bound: every entry is one more thing that has to be
+ * invalidated correctly, and an unbounded map makes a missed invalidation permanent. 200 is the same
+ * order as `RMM_REGISTRY_MAX_INSTANCES`, and eviction is least-recently-USED so an entry a surface
+ * keeps reading survives while a page visited once does not.
+ */
+const MAXIMUM_CACHED_READS = 200;
+/**
+ * Holds resource READ results between navigations, so a surface that was visited before does not
+ * re-fetch what nothing has changed.
+ *
+ * ## The problem, measured rather than assumed
+ *
+ * There is no cross-time read cache anywhere in the frontend today — `WildoBackendHttpClient` says
+ * so at its in-flight map: *"IN-FLIGHT sharing only … There is NO cross-time cache / TTL"*. That
+ * same comment records the cost: **one resource-detail mount fires ~9 GETs from 7 independent
+ * consumers**, and navigating away and back pays all of them again.
+ *
+ * ## Why an entry is not servable unless something is watching it
+ *
+ * The obvious cache — store the response, serve it next time, invalidate on a WebSocket event — has
+ * a hole that is silent rather than noisy. Resource events are delivered to ROOMS, and rooms are
+ * joined by subscription. An entry whose room nobody has joined receives no invalidation, so it is
+ * served confidently forever. Nothing errors, nothing retries; the data is simply wrong.
+ *
+ * So this tier inverts the default: a stored entry is a candidate, and only a
+ * {@link ResourceReadCoverageAuthority} reporting live coverage makes it servable. With no authority
+ * the tier stores and serves nothing, which is exactly today's behaviour — slow and correct.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * - **No TTL.** A time bound would be a guess about how stale is acceptable, and it would let an
+ *   uncovered entry be served for the length of the guess. Coverage is a fact; a TTL is a hope.
+ * - **No stale-while-revalidate.** Serving a known-stale value while refetching is a reasonable
+ *   pattern elsewhere; here it would silently reintroduce the wrong-data path this design exists to
+ *   close, and it cannot satisfy "a repeat navigation issues no request" anyway.
+ * - **No mutation caching.** Only read-family operations are ever stored.
+ */
+export class ResourceReadCacheFrontendService {
+    applicationId = null;
+    entries = new Map();
+    authority = null;
+    enabled = true;
+    /**
+     * Install the coverage authority. Called by the WebSocket layer once it can answer.
+     *
+     * Replacing an authority CLEARS the cache: the new one knows nothing about what the old one was
+     * covering, so every held entry is of unknown freshness. Clearing costs a refetch and cannot be
+     * wrong, which is the direction this tier always errs in.
+     */
+    /**
+     * The application this session is reading, for the one scope an APPLICATION-scoped resource has.
+     *
+     * `deriveResourceScopeRoomQualifiers` yields the `app` room only when `applicationId` is present in
+     * the context it is handed, and a read's context is built from the URL's contextual parameters —
+     * which never carry one, because an application id is ambient rather than addressed. So without
+     * this, an APPLICATION-scoped resource derives whatever incidental `org`/`user` rooms its
+     * parameters imply and never its own, and a push addressed to `app` reaches nobody (issue #283,
+     * measured: 0 frames on a surface whose companion had just published to it).
+     *
+     * Set by `ResourceReadCacheBridge`, which is a component and can read the app scope; the service is
+     * plain and cannot. Null until it does, which is correct — before the scope is mounted there is no
+     * application to name.
+     */
+    setApplicationId(applicationId) {
+        this.applicationId = applicationId;
+    }
+    getApplicationId() {
+        return this.applicationId;
+    }
+    setCoverageAuthority(authority) {
+        this.authority = authority;
+        this.entries.clear();
+        logDebug('coverage authority changed', { hasAuthority: authority !== null });
+    }
+    /**
+     * Turn the tier off entirely.
+     *
+     * A door rather than a design. The blast radius here is every generated application on every
+     * persistence adapter, so an operator who suspects the cache must be able to remove it from the
+     * picture without a rebuild.
+     *
+     * **The handle is `VITE_RESOURCE_READ_CACHE=off`**, applied by `ResourceReadCacheBridge` — mirroring
+     * `COMPANION_INTROSPECTION_CACHE=off` on the companion side, same word and same value so an
+     * operator who has met one knows the other. Said explicitly because a door with no handle is worse
+     * than no door: this method existed for a while with only a test calling it, while this comment
+     * claimed an operator could reach it.
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+        if (!enabled)
+            this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * The cached value for a read, or `undefined` when there is none that may be served.
+     *
+     * Coverage is re-checked on every read rather than recorded at store time, because coverage is a
+     * property of NOW: a socket that dropped since the entry was stored must stop the entry being
+     * served, and only asking at read time can see that.
+     */
+    read(key) {
+        if (!this.enabled)
+            return undefined;
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (!this.authority?.covers(entry.resourceType, entry.scopes)) {
+            // Not an error and not necessarily stale — simply unprovable. Dropping it keeps the map from
+            // filling with entries that can never be served.
+            this.entries.delete(key);
+            logDebug('entry dropped: no live coverage', { resourceType: entry.resourceType });
+            return undefined;
+        }
+        entry.lastReadAt = Date.now();
+        return entry.value;
+    }
+    /** Store a read result and ask the authority to start covering it. */
+    store(key, value, resourceType, scopes) {
+        if (!this.enabled || !this.authority)
+            return;
+        // A read belonging to no scope has no room through which an invalidation could arrive. Storing
+        // it would create an entry that can never be proven fresh — so it is refused at the door rather
+        // than kept and never served.
+        if (scopes.length === 0)
+            return;
+        this.authority.requestCoverage(resourceType, scopes);
+        const now = Date.now();
+        this.entries.set(key, { value, resourceType, scopes, storedAt: now, lastReadAt: now });
+        this.evictIfOverCapacity();
+    }
+    /**
+     * Drop every entry for a resource type.
+     *
+     * The invalidation the WebSocket layer calls. Deliberately coarse — per-row invalidation would
+     * have to know which cached LISTS contain that row, which is a question the cache cannot answer
+     * without parsing every stored payload against a shape it does not own.
+     */
+    invalidateResourceType(resourceType) {
+        let dropped = 0;
+        for (const [key, entry] of this.entries) {
+            if (entry.resourceType === resourceType) {
+                this.entries.delete(key);
+                dropped += 1;
+            }
+        }
+        if (dropped > 0)
+            logDebug('invalidated by resource type', { resourceType, dropped });
+    }
+    /**
+     * Drop everything.
+     *
+     * Called on the two transitions that change WHICH rows a read would return without changing the
+     * request: an organization switch and a session change. Both happen without a page reload, so
+     * nothing else would clear this.
+     */
+    clear() {
+        const dropped = this.entries.size;
+        this.entries.clear();
+        if (dropped > 0)
+            logDebug('cleared', { dropped });
+    }
+    /** Least-recently-READ eviction, so a surface being used keeps its entry. */
+    evictIfOverCapacity() {
+        if (this.entries.size <= MAXIMUM_CACHED_READS)
+            return;
+        let oldestKey;
+        let oldestAt = Number.POSITIVE_INFINITY;
+        for (const [key, entry] of this.entries) {
+            if (entry.lastReadAt < oldestAt) {
+                oldestAt = entry.lastReadAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey !== undefined)
+            this.entries.delete(oldestKey);
+    }
+}
+/**
+ * Render a read's identity so two structurally equal requests produce one key.
+ *
+ * Object keys are sorted at every depth: `{a:1,b:2}` and `{b:2,a:1}` are the same request, and
+ * without sorting the second phrasing of one question would always miss. Arrays keep their order,
+ * because in a filter or a sort an array's order is part of the question.
+ *
+ * Returns `null` for anything that cannot be rendered — a cycle, a `BigInt`, a function in a filter —
+ * which every caller reads as "do not cache this", never as an error.
+ */
+export function renderResourceReadCacheKey(operationPathKey, parameters) {
+    const seen = new WeakSet();
+    const render = (value) => {
+        if (value === undefined)
+            return 'u';
+        if (value === null)
+            return 'n';
+        if (typeof value === 'function')
+            throw new Error('not renderable');
+        if (typeof value === 'bigint')
+            throw new Error('not renderable');
+        if (typeof value !== 'object')
+            return JSON.stringify(value) ?? 'u';
+        if (seen.has(value))
+            throw new Error('not renderable');
+        seen.add(value);
+        if (Array.isArray(value))
+            return `[${value.map(render).join(',')}]`;
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${render(entryValue)}`).join(',')}}`;
+    };
+    try {
+        return `${operationPathKey}
${render(parameters)}`;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=resource-read-cache.frontend.service.js.map

package/dist/esm/core/resources/resource-read-cache.frontend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-read-cache.frontend.service.js","sourceRoot":"","sources":["../../../../src/core/resources/resource-read-cache.frontend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ResourceScopeRoomQualifier } from '@wildo-ai/saas-models';\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\n\nconst logger = LoggerFrontendService.getLogger();\nconst logDebug = logger.debugByType('ResourceReadCache');\nlogger.setDebugTypeLogging('ResourceReadCache', false);\n\n/**\n * A ceiling on how many read results are held.\n *\n * Not a memory bound so much as a staleness bound: every entry is one more thing that has to be\n * invalidated correctly, and an unbounded map makes a missed invalidation permanent. 200 is the same\n * order as `RMM_REGISTRY_MAX_INSTANCES`, and eviction is least-recently-USED so an entry a surface\n * keeps reading survives while a page visited once does not.\n */\nconst MAXIMUM_CACHED_READS = 200;\n\n/**\n * Whether a cached read is currently covered by something that would tell us it went stale.\n *\n * This is the whole safety contract. A cached read may be SERVED only while an authority reports\n * that every room an invalidation for it would arrive through is joined — so a cache entry can never\n * outlive the subscription that keeps it honest.\n *\n * Implemented by the WebSocket layer. Absent — no provider mounted, socket down, subscription\n * refused — nothing is ever served from cache, and the tier degrades to exactly today's behaviour.\n */\nexport interface ResourceReadCoverageAuthority {\n  /**\n   * Whether an invalidation for this resource in these scopes would currently reach us.\n   *\n   * Must answer `false` when the transport is down, when any required room is not joined, and when\n   * the scope set is EMPTY — a read that belongs to no room has no channel through which it could\n   * ever be told it is stale, so it is not cacheable at all.\n   */\n  covers(resourceType: string, scopes: readonly ResourceScopeRoomQualifier[]): boolean;\n\n  /**\n   * Asked to start covering a resource in these scopes. Best-effort and asynchronous: the entry it\n   * was requested for is not servable until a later `covers` returns `true`.\n   */\n  requestCoverage(resourceType: string, scopes: readonly ResourceScopeRoomQualifier[]): void;\n}\n\ninterface CachedRead {\n  readonly value: unknown;\n  readonly resourceType: string;\n  readonly scopes: readonly ResourceScopeRoomQualifier[];\n  readonly storedAt: number;\n  lastReadAt: number;\n}\n\n/**\n * Holds resource READ results between navigations, so a surface that was visited before does not\n * re-fetch what nothing has changed.\n *\n * ## The problem, measured rather than assumed\n *\n * There is no cross-time read cache anywhere in the frontend today — `WildoBackendHttpClient` says\n * so at its in-flight map: *\"IN-FLIGHT sharing only … There is NO cross-time cache / TTL\"*. That\n * same comment records the cost: **one resource-detail mount fires ~9 GETs from 7 independent\n * consumers**, and navigating away and back pays all of them again.\n *\n * ## Why an entry is not servable unless something is watching it\n *\n * The obvious cache — store the response, serve it next time, invalidate on a WebSocket event — has\n * a hole that is silent rather than noisy. Resource events are delivered to ROOMS, and rooms are\n * joined by subscription. An entry whose room nobody has joined receives no invalidation, so it is\n * served confidently forever. Nothing errors, nothing retries; the data is simply wrong.\n *\n * So this tier inverts the default: a stored entry is a candidate, and only a\n * {@link ResourceReadCoverageAuthority} reporting live coverage makes it servable. With no authority\n * the tier stores and serves nothing, which is exactly today's behaviour — slow and correct.\n *\n * ## What it deliberately does NOT do\n *\n * - **No TTL.** A time bound would be a guess about how stale is acceptable, and it would let an\n *   uncovered entry be served for the length of the guess. Coverage is a fact; a TTL is a hope.\n * - **No stale-while-revalidate.** Serving a known-stale value while refetching is a reasonable\n *   pattern elsewhere; here it would silently reintroduce the wrong-data path this design exists to\n *   close, and it cannot satisfy \"a repeat navigation issues no request\" anyway.\n * - **No mutation caching.** Only read-family operations are ever stored.\n */\nexport class ResourceReadCacheFrontendService {\n  private applicationId: string | null = null;\n\n  private readonly entries = new Map<string, CachedRead>();\n  private authority: ResourceReadCoverageAuthority | null = null;\n  private enabled = true;\n\n  /**\n   * Install the coverage authority. Called by the WebSocket layer once it can answer.\n   *\n   * Replacing an authority CLEARS the cache: the new one knows nothing about what the old one was\n   * covering, so every held entry is of unknown freshness. Clearing costs a refetch and cannot be\n   * wrong, which is the direction this tier always errs in.\n   */\n  /**\n   * The application this session is reading, for the one scope an APPLICATION-scoped resource has.\n   *\n   * `deriveResourceScopeRoomQualifiers` yields the `app` room only when `applicationId` is present in\n   * the context it is handed, and a read's context is built from the URL's contextual parameters —\n   * which never carry one, because an application id is ambient rather than addressed. So without\n   * this, an APPLICATION-scoped resource derives whatever incidental `org`/`user` rooms its\n   * parameters imply and never its own, and a push addressed to `app` reaches nobody (issue #283,\n   * measured: 0 frames on a surface whose companion had just published to it).\n   *\n   * Set by `ResourceReadCacheBridge`, which is a component and can read the app scope; the service is\n   * plain and cannot. Null until it does, which is correct — before the scope is mounted there is no\n   * application to name.\n   */\n  public setApplicationId(applicationId: string | null): void {\n    this.applicationId = applicationId;\n  }\n\n  public getApplicationId(): string | null {\n    return this.applicationId;\n  }\n\n  public setCoverageAuthority(authority: ResourceReadCoverageAuthority | null): void {\n    this.authority = authority;\n    this.entries.clear();\n    logDebug('coverage authority changed', { hasAuthority: authority !== null });\n  }\n\n  /**\n   * Turn the tier off entirely.\n   *\n   * A door rather than a design. The blast radius here is every generated application on every\n   * persistence adapter, so an operator who suspects the cache must be able to remove it from the\n   * picture without a rebuild.\n   *\n   * **The handle is `VITE_RESOURCE_READ_CACHE=off`**, applied by `ResourceReadCacheBridge` — mirroring\n   * `COMPANION_INTROSPECTION_CACHE=off` on the companion side, same word and same value so an\n   * operator who has met one knows the other. Said explicitly because a door with no handle is worse\n   * than no door: this method existed for a while with only a test calling it, while this comment\n   * claimed an operator could reach it.\n   */\n  public setEnabled(enabled: boolean): void {\n    this.enabled = enabled;\n    if (!enabled) this.entries.clear();\n  }\n\n  public get size(): number {\n    return this.entries.size;\n  }\n\n  /**\n   * The cached value for a read, or `undefined` when there is none that may be served.\n   *\n   * Coverage is re-checked on every read rather than recorded at store time, because coverage is a\n   * property of NOW: a socket that dropped since the entry was stored must stop the entry being\n   * served, and only asking at read time can see that.\n   */\n  public read(key: string): unknown | undefined {\n    if (!this.enabled) return undefined;\n    const entry = this.entries.get(key);\n    if (!entry) return undefined;\n\n    if (!this.authority?.covers(entry.resourceType, entry.scopes)) {\n      // Not an error and not necessarily stale — simply unprovable. Dropping it keeps the map from\n      // filling with entries that can never be served.\n      this.entries.delete(key);\n      logDebug('entry dropped: no live coverage', { resourceType: entry.resourceType });\n      return undefined;\n    }\n\n    entry.lastReadAt = Date.now();\n    return entry.value;\n  }\n\n  /** Store a read result and ask the authority to start covering it. */\n  public store(\n    key: string,\n    value: unknown,\n    resourceType: string,\n    scopes: readonly ResourceScopeRoomQualifier[],\n  ): void {\n    if (!this.enabled || !this.authority) return;\n    // A read belonging to no scope has no room through which an invalidation could arrive. Storing\n    // it would create an entry that can never be proven fresh — so it is refused at the door rather\n    // than kept and never served.\n    if (scopes.length === 0) return;\n\n    this.authority.requestCoverage(resourceType, scopes);\n\n    const now = Date.now();\n    this.entries.set(key, { value, resourceType, scopes, storedAt: now, lastReadAt: now });\n    this.evictIfOverCapacity();\n  }\n\n  /**\n   * Drop every entry for a resource type.\n   *\n   * The invalidation the WebSocket layer calls. Deliberately coarse — per-row invalidation would\n   * have to know which cached LISTS contain that row, which is a question the cache cannot answer\n   * without parsing every stored payload against a shape it does not own.\n   */\n  public invalidateResourceType(resourceType: string): void {\n    let dropped = 0;\n    for (const [key, entry] of this.entries) {\n      if (entry.resourceType === resourceType) {\n        this.entries.delete(key);\n        dropped += 1;\n      }\n    }\n    if (dropped > 0) logDebug('invalidated by resource type', { resourceType, dropped });\n  }\n\n  /**\n   * Drop everything.\n   *\n   * Called on the two transitions that change WHICH rows a read would return without changing the\n   * request: an organization switch and a session change. Both happen without a page reload, so\n   * nothing else would clear this.\n   */\n  public clear(): void {\n    const dropped = this.entries.size;\n    this.entries.clear();\n    if (dropped > 0) logDebug('cleared', { dropped });\n  }\n\n  /** Least-recently-READ eviction, so a surface being used keeps its entry. */\n  private evictIfOverCapacity(): void {\n    if (this.entries.size <= MAXIMUM_CACHED_READS) return;\n    let oldestKey: string | undefined;\n    let oldestAt = Number.POSITIVE_INFINITY;\n    for (const [key, entry] of this.entries) {\n      if (entry.lastReadAt < oldestAt) {\n        oldestAt = entry.lastReadAt;\n        oldestKey = key;\n      }\n    }\n    if (oldestKey !== undefined) this.entries.delete(oldestKey);\n  }\n}\n\n/**\n * Render a read's identity so two structurally equal requests produce one key.\n *\n * Object keys are sorted at every depth: `{a:1,b:2}` and `{b:2,a:1}` are the same request, and\n * without sorting the second phrasing of one question would always miss. Arrays keep their order,\n * because in a filter or a sort an array's order is part of the question.\n *\n * Returns `null` for anything that cannot be rendered — a cycle, a `BigInt`, a function in a filter —\n * which every caller reads as \"do not cache this\", never as an error.\n */\nexport function renderResourceReadCacheKey(\n  operationPathKey: string,\n  parameters: unknown,\n): string | null {\n  const seen = new WeakSet<object>();\n\n  const render = (value: unknown): string => {\n    if (value === undefined) return 'u';\n    if (value === null) return 'n';\n    if (typeof value === 'function') throw new Error('not renderable');\n    if (typeof value === 'bigint') throw new Error('not renderable');\n    if (typeof value !== 'object') return JSON.stringify(value) ?? 'u';\n    if (seen.has(value as object)) throw new Error('not renderable');\n    seen.add(value as object);\n    if (Array.isArray(value)) return `[${value.map(render).join(',')}]`;\n    const entries = Object.entries(value as Record<string, unknown>)\n      .filter(([, entryValue]) => entryValue !== undefined)\n      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));\n    return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${render(entryValue)}`).join(',')}}`;\n  };\n\n  try {\n    return `${operationPathKey}\u0001${render(parameters)}`;\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/esm/core/resources/resources-repository.frontend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources-repository.frontend.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/resources/resources-repository.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sEAAsE,CAAC;AAC9G,OAAO,EAAE,gCAAgC,EAAE,MAAM,gFAAgF,CAAC;AAOlI,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+DAA+D,CAAC;AAIxG,OAAO,EAGL,2CAA2C,EAE3C,oBAAoB,EAqBrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEV,2BAA2B,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAGV,yBAAyB,EAE1B,MAAM,+DAA+D,CAAC;AAgJvE,qBAAa,kCAAkC;IAM3C,OAAO,CAAC,UAAU;IALpB,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,mBAAmB,CAAiD;gBAGlE,UAAU,EAAE,sBAAsB;IAG5C;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;;;;;;;OASG;IACU,mBAAmB,CAC9B,8CAA8C,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,2CAA2C,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;KAAE,EAC9H,oCAAoC,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EAChE,mCAAmC,CAAC,EAAE,oBAAoB,EAAE,EAC5D,qBAAqB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EAC3C,kBAAkB,CAAC,EAAE,kBAAkB,EACvC,kCAAkC,CAAC,EAAE,2BAA2B,EAAE,GACjE,OAAO,CAAC,IAAI,CAAC;IAmPhB,OAAO,CAAC,2CAA2C;IA4BnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,8BAA8B;IA0BtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,mCAAmC;IAyN3C,OAAO,CAAC,qCAAqC;IAsB7C,OAAO,CAAC,qCAAqC;IAsC7C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mCAAmC;IAwJ3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,wCAAwC;IAsFhD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;IAyChC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;OAEG;IACI,oBAAoB,IAAI,yBAAyB;IAUxD;;OAEG;IACI,yBAAyB,IAAI,MAAM,EAAE;IAO5C;;OAEG;IACI,eAAe,IAAI;QACxB,uBAAuB,EAAE,MAAM,EAAE,CAAC;KACnC;IAUD;;;OAGG;IACI,sBAAsB,IAAI,gCAAgC;IAUjE;;;;;;;;;;;;OAYG;IACI,wBAAwB,IAAI,sBAAsB;IAIzD;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAuCpC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kCAAkC;IAoD1C;;;;;;OAMG;IACH,OAAO,CAAC,sCAAsC;CAkC/C"}
+{"version":3,"file":"resources-repository.frontend.service.d.ts","sourceRoot":"","sources":["../../../../src/core/resources/resources-repository.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sEAAsE,CAAC;AAC9G,OAAO,EAAE,gCAAgC,EAAE,MAAM,gFAAgF,CAAC;AAOlI,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+DAA+D,CAAC;AAIxG,OAAO,EAGL,2CAA2C,EAE3C,oBAAoB,EAqBrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEV,2BAA2B,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAGV,yBAAyB,EAE1B,MAAM,+DAA+D,CAAC;AAgJvE,qBAAa,kCAAkC;IAM3C,OAAO,CAAC,UAAU;IALpB,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,mBAAmB,CAAiD;gBAGlE,UAAU,EAAE,sBAAsB;IAG5C;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;;;;;;;OASG;IACU,mBAAmB,CAC9B,8CAA8C,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,2CAA2C,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;KAAE,EAC9H,oCAAoC,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EAChE,mCAAmC,CAAC,EAAE,oBAAoB,EAAE,EAC5D,qBAAqB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EAC3C,kBAAkB,CAAC,EAAE,kBAAkB,EACvC,kCAAkC,CAAC,EAAE,2BAA2B,EAAE,GACjE,OAAO,CAAC,IAAI,CAAC;IAmPhB,OAAO,CAAC,2CAA2C;IA4BnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,8BAA8B;IA0BtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,mCAAmC;IAyN3C,OAAO,CAAC,qCAAqC;IAsB7C,OAAO,CAAC,qCAAqC;IAsC7C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mCAAmC;IAwJ3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,wCAAwC;IAsFhD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;IAyChC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;OAEG;IACI,oBAAoB,IAAI,yBAAyB;IAUxD;;OAEG;IACI,yBAAyB,IAAI,MAAM,EAAE;IAO5C;;OAEG;IACI,eAAe,IAAI;QACxB,uBAAuB,EAAE,MAAM,EAAE,CAAC;KACnC;IAUD;;;OAGG;IACI,sBAAsB,IAAI,gCAAgC;IAUjE;;;;;;;;;;;;OAYG;IACI,wBAAwB,IAAI,sBAAsB;IAIzD;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAuCpC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kCAAkC;IAoD1C;;;;;;OAMG;IACH,OAAO,CAAC,sCAAsC;CAkC/C"}