@basaltkit/files 1.1.1 → 1.2.0

package/dist/files.d.ts

@@ -48,6 +48,12 @@ export interface UploadInput {
     uploadedBy?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Store key every record is filed under when the app has no tenancy at all.
+ * The {@link FileStore} contract is tenant-keyed, so a single-tenant app still
+ * needs one stable key — it just shouldn't have to invent it.
+ */
+export declare const SINGLE_TENANT_SCOPE = "default";
 /**
  * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
  * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
@@ -55,6 +61,13 @@ export interface UploadInput {
  * context so files are isolated whether called from a request or a job.
  */
 export declare class Files {
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `filesPlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import, so this generic package never depends on the opt-in SaaS
+     * layer. Defaults to `false` (single-tenant).
+     */
+    private readonly tenancyActive;
     private readonly disk;
     private readonly store;
     private readonly hooks;
@@ -62,7 +75,14 @@ export declare class Files {
     private readonly maxTotalBytes;
     private readonly checkQuota;
     private readonly now;
-    constructor(options: FilesOptions);
+    constructor(options: FilesOptions, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `filesPlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import, so this generic package never depends on the opt-in SaaS
+     * layer. Defaults to `false` (single-tenant).
+     */
+    tenancyActive?: () => boolean);
     upload(content: Buffer, input: UploadInput): Promise<FileRecord>;
     get(id: string, tenantId?: string): Promise<FileRecord | null>;
     list(tenantId?: string): Promise<FileRecord[]>;
@@ -87,7 +107,20 @@ export declare class Files {
     }, tenantId?: string): Promise<FileRecord>;
     private validate;
     private enforceQuota;
+    /**
+     * The tenant a call is scoped to, or `undefined` when the app has no tenancy.
+     *
+     * With `@basaltkit/tenancy` registered an unresolvable tenant is an error: an
+     * unscoped read or write would cross tenants. Without it there is no tenant
+     * dimension and nothing to cross.
+     */
     private tenant;
-    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+    /** The {@link FileStore} key: the tenant, or {@link SINGLE_TENANT_SCOPE}. */
+    private scope;
+    /**
+     * Runs a storage op in the resolved tenant's context so the disk scopes
+     * correctly. With no tenancy there is no tenant context to synthesize — the
+     * disk keeps its own (unscoped) default, so paths match plain `@basaltkit/storage`.
+     */
     private inTenant;
 }

package/dist/files.js

@@ -36,6 +36,12 @@ export class FileTenantRequiredError extends BasaltError {
 }
 const matchesType = (contentType, allowed) => allowed.some((a) => a === contentType || (a.endsWith('/*') && contentType.startsWith(a.slice(0, -1))));
 const storagePath = (id) => `files/${id}`;
+/**
+ * Store key every record is filed under when the app has no tenancy at all.
+ * The {@link FileStore} contract is tenant-keyed, so a single-tenant app still
+ * needs one stable key — it just shouldn't have to invent it.
+ */
+export const SINGLE_TENANT_SCOPE = 'default';
 /**
  * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
  * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
@@ -43,6 +49,7 @@ const storagePath = (id) => `files/${id}`;
  * context so files are isolated whether called from a request or a job.
  */
 export class Files {
+    tenancyActive;
     disk;
     store;
     hooks;
@@ -50,7 +57,15 @@ export class Files {
     maxTotalBytes;
     checkQuota;
     now;
-    constructor(options) {
+    constructor(options, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `filesPlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import, so this generic package never depends on the opt-in SaaS
+     * layer. Defaults to `false` (single-tenant).
+     */
+    tenancyActive = () => false) {
+        this.tenancyActive = tenancyActive;
         this.disk = options.disk;
         this.store = options.store ?? new MemoryFileStore();
         this.hooks = options.hooks;
@@ -63,16 +78,17 @@ export class Files {
     }
     async upload(content, input) {
         const tenantId = this.tenant(input.tenantId);
+        const scope = tenantId ?? SINGLE_TENANT_SCOPE;
         const size = content.length;
         this.validate(input.contentType, size);
-        await this.enforceQuota(tenantId, size);
+        await this.enforceQuota(scope, size);
         const id = randomUUID();
         const path = storagePath(id);
         const checksum = createHash('sha256').update(content).digest('hex');
         await this.inTenant(tenantId, () => this.disk.put(path, content, { contentType: input.contentType }));
         const record = {
             id,
-            tenantId,
+            tenantId: scope,
             name: input.name,
             contentType: input.contentType,
             size,
@@ -87,14 +103,14 @@ export class Files {
         return record;
     }
     async get(id, tenantId) {
-        return this.store.find(this.tenant(tenantId), id);
+        return this.store.find(this.scope(tenantId), id);
     }
     async list(tenantId) {
-        return this.store.list(this.tenant(tenantId));
+        return this.store.list(this.scope(tenantId));
     }
     async download(id, tenantId) {
         const resolved = this.tenant(tenantId);
-        const record = await this.store.find(resolved, id);
+        const record = await this.store.find(resolved ?? SINGLE_TENANT_SCOPE, id);
         if (!record)
             throw new FileNotFoundError();
         const content = await this.inTenant(resolved, () => this.disk.get(record.path));
@@ -108,23 +124,24 @@ export class Files {
      */
     async temporaryUrl(id, expiresIn, tenantId, options = {}) {
         const resolved = this.tenant(tenantId);
-        const record = await this.store.find(resolved, id);
+        const record = await this.store.find(resolved ?? SINGLE_TENANT_SCOPE, id);
         if (!record)
             throw new FileNotFoundError();
         return this.inTenant(resolved, () => this.disk.temporaryUrl(record.path, expiresIn, options));
     }
     async delete(id, tenantId) {
         const resolved = this.tenant(tenantId);
-        const record = await this.store.find(resolved, id);
+        const scope = resolved ?? SINGLE_TENANT_SCOPE;
+        const record = await this.store.find(scope, id);
         if (!record)
             return;
         await this.inTenant(resolved, () => this.disk.delete(record.path));
-        await this.store.delete(resolved, id);
-        await this.hooks?.emit('file:deleted', { tenantId: resolved, id });
+        await this.store.delete(scope, id);
+        await this.hooks?.emit('file:deleted', { tenantId: scope, id });
     }
     /** Records the result of an out-of-band scan (antivirus, moderation, …). */
     async markScanned(id, result, tenantId) {
-        const resolved = this.tenant(tenantId);
+        const resolved = this.scope(tenantId);
         const record = await this.store.find(resolved, id);
         if (!record)
             throw new FileNotFoundError();
@@ -149,14 +166,33 @@ export class Files {
         }
         await this.checkQuota?.(tenantId, size);
     }
+    /**
+     * The tenant a call is scoped to, or `undefined` when the app has no tenancy.
+     *
+     * With `@basaltkit/tenancy` registered an unresolvable tenant is an error: an
+     * unscoped read or write would cross tenants. Without it there is no tenant
+     * dimension and nothing to cross.
+     */
     tenant(explicit) {
         const id = explicit ?? tryCtx()?.['tenant']?.id;
-        if (!id)
+        if (id)
+            return id;
+        if (this.tenancyActive())
             throw new FileTenantRequiredError();
-        return id;
+        return undefined;
     }
-    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+    /** The {@link FileStore} key: the tenant, or {@link SINGLE_TENANT_SCOPE}. */
+    scope(explicit) {
+        return this.tenant(explicit) ?? SINGLE_TENANT_SCOPE;
+    }
+    /**
+     * Runs a storage op in the resolved tenant's context so the disk scopes
+     * correctly. With no tenancy there is no tenant context to synthesize — the
+     * disk keeps its own (unscoped) default, so paths match plain `@basaltkit/storage`.
+     */
     inTenant(tenantId, fn) {
+        if (tenantId === undefined)
+            return fn();
         return runWithContext({ tenant: { id: tenantId } }, fn);
     }
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { Files, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, type FilesOptions, type FileValidation, type UploadInput, } from './files.js';
+export { Files, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, SINGLE_TENANT_SCOPE, type FilesOptions, type FileValidation, type UploadInput, } from './files.js';
 export { MemoryFileStore, type FileRecord, type FileStore, type FilePatch, } from './store.js';
 export { filesPlugin, fileRoutes, FILES, type FilesPluginOptions } from './plugin.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { Files, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, } from './files.js';
+export { Files, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, SINGLE_TENANT_SCOPE, } from './files.js';
 export { MemoryFileStore, } from './store.js';
 export { filesPlugin, fileRoutes, FILES } from './plugin.js';

package/dist/plugin.js

@@ -1,4 +1,4 @@
-import { createToken, ctx, definePlugin } from '@basaltkit/core';
+import { createToken, ctx, definePlugin, ensureMetadata } from '@basaltkit/core';
 import { STORAGE } from '@basaltkit/storage';
 import { route } from '@basaltkit/http';
 import { z } from 'zod';
@@ -8,6 +8,9 @@ export function filesPlugin(options) {
     return definePlugin({
         name: 'basalt:files',
         register({ container, hooks }) {
+            // 'tenancy:active' is tenancyPlugin's marker: how a generic package
+            // learns the app is multi-tenant without importing @basaltkit/tenancy.
+            const metadata = ensureMetadata(container);
             container.singleton(FILES, () => {
                 const disk = typeof options.disk === 'string' ? container.get(STORAGE).disk(options.disk) : options.disk;
                 return new Files({
@@ -17,7 +20,7 @@ export function filesPlugin(options) {
                     ...(options.validate ? { validate: options.validate } : {}),
                     ...(options.maxTotalBytes !== undefined ? { maxTotalBytes: options.maxTotalBytes } : {}),
                     ...(options.checkQuota ? { checkQuota: options.checkQuota } : {}),
-                });
+                }, () => metadata.get('tenancy:active').length > 0);
             });
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/files",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "engines": {
     "node": ">=22.5.0"
   },