@_linked/core 2.18.1 → 2.20.1

package/lib/esm/utils/LinkedFileStorage.js

@@ -1,39 +1,191 @@
+/**
+ * Well-known file store purposes shipped with core.
+ *
+ * Core itself never writes to `appAssets`; it lives here as the documented
+ * convention (plan 011 D4) so the CLI and apps agree on the same key without a
+ * shared runtime dependency. Any *new* purpose's constant belongs in the
+ * runtime package that owns the concept, not here and not in the CLI.
+ */
+export const FileStorePurposes = {
+    /** User-generated files. Resolves to the default store unless split out. */
+    uploads: 'uploads',
+    /** Built app bundles published by `linked build-app`. */
+    appAssets: 'appAssets',
+};
 export class LinkedFileStorage {
     static get accessURL() {
         // check if default store is not set, return default accessURL
-        if (!this.defaultDataset) {
+        if (!this.defaultStore) {
             return this.url;
         }
-        return this.defaultDataset.accessURL;
+        return this.defaultStore.accessURL;
     }
     static setDefaultAccessURL(accessURL) {
         return (this.url = accessURL);
     }
+    static getDefaultStore() {
+        return this.defaultStore;
+    }
+    /**
+     * Configure the default store: the fallback for *every* purpose, `uploads`
+     * included.
+     *
+     * It deliberately writes no entry into the purpose → store map, so `uploads`
+     * behaves exactly like `appAssets`: an explicit `setStore('uploads', other)`
+     * wins whenever it is called, before or after this, and `hasStore('uploads')`
+     * stays false until such a call is made.
+     */
+    static setDefaultStore(store) {
+        this.defaultStore = store;
+        if (this.defaultStore.init) {
+            this.defaultStore.init();
+        }
+    }
+    /** @deprecated use {@link LinkedFileStorage.getDefaultStore} */
     static getDefaultDataset() {
-        return this.defaultDataset;
+        return this.getDefaultStore();
     }
+    /** @deprecated use {@link LinkedFileStorage.setDefaultStore} */
     static setDefaultDataset(dataset) {
-        this.defaultDataset = dataset;
-        if (this.defaultDataset.init) {
-            this.defaultDataset.init();
+        this.setDefaultStore(dataset);
+    }
+    /**
+     * Declare a purpose without configuring a store for it.
+     *
+     * A package that *reads* a purpose the app may leave unconfigured registers
+     * it in the same module that exports its constant, so importing the constant
+     * is the registration and ordering resolves itself.
+     */
+    static registerPurpose(purpose, info = {}) {
+        var _a;
+        const existing = this.purposes.get(purpose);
+        // Keep an existing description rather than blanking it on a re-register.
+        this.purposes.set(purpose, {
+            description: (_a = info.description) !== null && _a !== void 0 ? _a : existing === null || existing === void 0 ? void 0 : existing.description,
+        });
+    }
+    /** Configure the store for a purpose. Also registers the purpose. */
+    static setStore(purpose, store) {
+        this.registerPurpose(purpose);
+        this.stores.set(purpose, store);
+        if (store.init) {
+            store.init();
         }
     }
+    /**
+     * Resolve the store for a purpose (plan 011 D2):
+     * - configured        → that store;
+     * - registered, not configured → the default store, logged once;
+     * - not registered    → throws.
+     *
+     * Unregistered throws on purpose: only a registry can tell "the app did not
+     * split this purpose out" apart from a typo. Without it, `'appAsset'` would
+     * silently write release bundles into the uploads store.
+     *
+     * The returned store is a **live reference**, resolved once at call time. A
+     * caller that holds on to a store returned through the default-store fallback
+     * keeps that object even after a later `setStore(purpose, other)`; call
+     * `getStore` again per operation if the configuration can change at runtime.
+     */
+    static getStore(purpose) {
+        const configured = this.stores.get(purpose);
+        if (configured) {
+            return configured;
+        }
+        if (!this.purposes.has(purpose)) {
+            throw new Error(`Unknown file store purpose '${purpose}'. Register it with LinkedFileStorage.setStore(), ` +
+                `or import the package that defines it. Known purposes: ${this.listPurposes()
+                    .map((entry) => entry.purpose)
+                    .join(', ') || '(none)'}`);
+        }
+        if (!this.defaultStore) {
+            throw new Error(`No file store is configured for purpose '${purpose}', and no default store is configured. ` +
+                `Call LinkedFileStorage.setStore('${purpose}', store) or LinkedFileStorage.setDefaultStore(store).`);
+        }
+        if (!this.loggedFallbacks.has(purpose)) {
+            this.loggedFallbacks.add(purpose);
+            // `debug`, not `info`: falling back is the normal configuration for an
+            // app that runs one store, so this must not read as a problem or show up
+            // in default-level logs. It stays available when diagnosing which store a
+            // purpose actually resolved to.
+            console.debug(`[LinkedFileStorage] Purpose '${purpose}' has no dedicated store; using the default store.`);
+        }
+        return this.defaultStore;
+    }
+    /**
+     * Whether a store was *explicitly configured* for this purpose.
+     *
+     * The default-store fallback is deliberately ignored: `hasStore(p)` is false
+     * while `getStore(p)` still returns a usable store via the default. Use this
+     * to ask "did the app split this purpose out?", never as a guard before
+     * `getStore` — that would skip a perfectly working fallback.
+     */
+    static hasStore(purpose) {
+        return this.stores.has(purpose);
+    }
+    /** Every declared purpose, with whether it has its own store. */
+    static listPurposes() {
+        return Array.from(this.purposes.entries()).map(([purpose, info]) => ({
+            purpose,
+            description: info.description,
+            configured: this.stores.has(purpose),
+        }));
+    }
+    /** The access URL of the store resolved for this purpose. */
+    static accessURLFor(purpose) {
+        return this.getStore(purpose).accessURL;
+    }
     static deleteFile(filePath) {
-        return this.defaultDataset.deleteFile(filePath);
+        return this.defaultStore.deleteFile(filePath);
     }
     static fileExists(filePath) {
-        return this.defaultDataset.fileExists(filePath);
+        return this.defaultStore.fileExists(filePath);
     }
     static getFile(filePath) {
-        return this.defaultDataset.getFile(filePath);
+        return this.defaultStore.getFile(filePath);
     }
     static listFiles(prefix) {
-        return this.defaultDataset.listFiles(prefix);
+        return this.defaultStore.listFiles(prefix);
     }
-    static saveFile(filePath, fileContent, mimeType, preventDuplicates = false) {
-        return this.defaultDataset.saveFile(filePath, fileContent, mimeType, preventDuplicates);
+    static saveFile(filePath, fileContent, options, 
+    /**
+     * Forwarded exactly as given. No default here on purpose: "unspecified"
+     * must reach the store so it can apply its own default.
+     */
+    preventDuplicates) {
+        return this.defaultStore.saveFile(filePath, fileContent, options, preventDuplicates);
     }
+    /**
+     * Clears the module-global registry and default store.
+     * For tests only — the registry is process-wide state.
+     *
+     * @internal
+     */
+    static resetForTests() {
+        this.stores.clear();
+        this.purposes.clear();
+        this.loggedFallbacks.clear();
+        this.defaultStore = undefined;
+        this.url = undefined;
+        registerWellKnownPurposes();
+    }
+}
+/** Purpose → the store configured for it. */
+LinkedFileStorage.stores = new Map();
+/** Every declared purpose, configured or not. */
+LinkedFileStorage.purposes = new Map();
+/** Purposes already reported as falling back, so the log fires once each. */
+LinkedFileStorage.loggedFallbacks = new Set();
+/** The purposes core ships with are declared at module load. */
+function registerWellKnownPurposes() {
+    LinkedFileStorage.registerPurpose(FileStorePurposes.uploads, {
+        description: 'User-generated files. Falls back to the default store.',
+    });
+    LinkedFileStorage.registerPurpose(FileStorePurposes.appAssets, {
+        description: 'Built app bundles published by `linked build-app`.',
+    });
 }
+registerWellKnownPurposes();
 /**
  * Get the full path of an asset based on the way LinkedFileStorage is configured
  * Returns accessURL + directory (/public by default) + path

package/lib/esm/utils/LinkedFileStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"LinkedFileStorage.js","sourceRoot":"","sources":["../../../src/utils/LinkedFileStorage.ts"],"names":[],"mappings":"AAGA,MAAM,OAAgB,iBAAiB;IAIrC,MAAM,KAAK,SAAS;QAClB,8DAA8D;QAC9D,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,GAAG,CAAC;QAClB,CAAC;QAED,OAAO,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC;IACvC,CAAC;IAED,MAAM,CAAC,mBAAmB,CAAC,SAAiB;QAC1C,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,CAAC,iBAAiB;QACtB,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,OAAmB;QAC1C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAE9B,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;YAC7B,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,QAAgB;QAChC,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,QAAgB;QAChC,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,QAAgB;QAC7B,OAAO,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,MAAe;QAC9B,OAAO,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,QAAQ,CACb,QAAgB,EAChB,WAAoD,EACpD,QAAiB,EACjB,oBAA6B,KAAK;QAElC,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,CACjC,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,iBAAiB,CAClB,CAAC;IACJ,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,YAAoB,SAAS;IAC/D,2EAA2E;IAC3E,sEAAsE;IACtE,wEAAwE;IACxE,0EAA0E;IAC1E,6CAA6C;IAC7C,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,iBAAiB,CAAC,SAAS,CAAC;IAC9C,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC;IAC9C,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"LinkedFileStorage.js","sourceRoot":"","sources":["../../../src/utils/LinkedFileStorage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@_linked/core",
-  "version": "2.18.1",
+  "version": "2.20.1",
+  "packageManager": "npm@11.19.1",
   "license": "MIT",
   "linkedPackage": true,
   "type": "module",
   "description": "Linked.js core query and SHACL shape DSL (copy-then-prune baseline)",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/linked-cm/core.git"
+    "url": "git+https://github.com/linked-fw/core.git"
   },
   "main": "lib/esm/index.js",
   "module": "lib/esm/index.js",