@byline/core 4.0.0 → 4.2.0

package/dist/services/field-upload.js

@@ -9,6 +9,7 @@ import { resolveUploadHooks } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_DATABASE, ERR_STORAGE, ERR_VALIDATION } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
+import { resolveUploadFilename } from '../utils/slugify-filename.js';
 import { createDocument } from './document-lifecycle/index.js';
 function isMimeTypeAllowed(mimeType, allowedTypes) {
     return allowedTypes.some((allowed) => {
@@ -21,17 +22,6 @@ function isMimeTypeAllowed(mimeType, allowedTypes) {
         return allowed === mimeType;
     });
 }
-function sanitiseFilename(filename) {
-    const lastDot = filename.lastIndexOf('.');
-    const ext = lastDot !== -1 ? filename.slice(lastDot).toLowerCase() : '';
-    const base = lastDot !== -1 ? filename.slice(0, lastDot) : filename;
-    const safe = base
-        .toLowerCase()
-        .replace(/[^a-z0-9._-]/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '');
-    return `${safe || 'file'}${ext}`;
-}
 /**
  * Walk a field set (recursing into `group` / `array` / `blocks`) and
  * locate the `image | file` field with the given name. Returns the
@@ -73,7 +63,7 @@ function normalizeUploadHook(hook) {
  *
  *   - return a string or `{ filename }` to substitute a new filename;
  *   - return `{ storagePath }` to take full control of the storage key
- *     (bypasses provider key derivation — no UUID prefix). When set
+ *     (bypasses provider key derivation — no entropy suffix). When set
  *     without `filename`, the filename defaults to the path's basename;
  *   - return `{ error }` to short-circuit with `ERR_VALIDATION`;
  *   - return `void` / `undefined` to leave current values unchanged.
@@ -182,7 +172,14 @@ export async function uploadField(ctx, params) {
         //    was supplied at the upload entry we hand them an empty one
         //    rather than throw — `assertActorCanPerform` is the auth gate
         //    for whether the upload should run at all, not the hook layer.
-        const sanitised = sanitiseFilename(originalFilename || 'upload');
+        //    The filename is slugified first (installation
+        //    `uploads.filenameSlugifier`, else the default) so hooks observe
+        //    the storage-ready base name.
+        const sanitised = resolveUploadFilename(originalFilename || 'upload', ctx.filenameSlugifier, {
+            collectionPath,
+            fieldName,
+            mimeType,
+        });
         // Resolve the field's upload hooks once. The loader form
         // (`hooks: () => import('./media.hooks.js')`) keeps server-only hook
         // graphs out of the client bundle; the inline form returns as-is.
@@ -216,6 +213,11 @@ export async function uploadField(ctx, params) {
                 mimeType,
                 size: fileSize,
                 collection: collectionPath,
+                // Declarative storage-key scope (`upload.location`). Providers use
+                // it in place of the collection default while keeping their own
+                // entropy + sanitisation. An explicit hook `storagePath` still wins
+                // (targetStoragePath is written verbatim, below).
+                ...(upload.location !== undefined && { location: upload.location }),
                 ...(effectiveStoragePath !== undefined && { targetStoragePath: effectiveStoragePath }),
             });
         }

package/dist/services/field-upload.test.node.js

@@ -333,7 +333,7 @@ describe('uploadField service', () => {
             fileSize: 3,
             shouldCreateDocument: false,
         });
-        // Explicit key is handed to the provider verbatim — no UUID prefix,
+        // Explicit key is handed to the provider verbatim — no entropy suffix,
         // no collection-derived key.
         expect(upload).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({
             targetStoragePath: 'publications/forru-0000447-0001-en.png',

package/dist/services/populate.d.ts

@@ -25,7 +25,7 @@
  * documents. The guard is in place from day one so that the hook work
  * in Phase 4+ cannot reintroduce the problem.
  *
- * See docs/04-collections/02-relationships.md for the full design rationale.
+ * See docs/04-collections/03-relationships.md for the full design rationale.
  *
  * ---------------------------------------------------------------------
  * DSL summary

package/dist/services/populate.js

@@ -25,7 +25,7 @@
  * documents. The guard is in place from day one so that the hook work
  * in Phase 4+ cannot reintroduce the problem.
  *
- * See docs/04-collections/02-relationships.md for the full design rationale.
+ * See docs/04-collections/03-relationships.md for the full design rationale.
  *
  * ---------------------------------------------------------------------
  * DSL summary

package/dist/storage/collection-fingerprint.js

@@ -62,6 +62,10 @@ function canonicalField(field) {
             return base;
         case 'text':
         case 'textArea':
+        // `code` folds in `validation` only — `language` / `languageField` are
+        // presentation hints for the admin editor and never affect the stored
+        // value's shape, so (like labels) they stay out of the fingerprint.
+        case 'code':
         case 'richText':
         case 'float':
         case 'integer':
@@ -86,6 +90,11 @@ function canonicalUpload(u) {
         out.mimeTypes = [...u.mimeTypes].sort();
     if (u.maxFileSize !== undefined)
         out.maxFileSize = u.maxFileSize;
+    // Storage-key scope: where new uploads land is part of the field's
+    // storage contract (existing objects never move on change, but the
+    // declaration itself is schema-shape).
+    if (u.location !== undefined)
+        out.location = u.location;
     if (u.sizes !== undefined) {
         out.sizes = u.sizes
             .map((s) => ({

package/dist/storage/field-store-map.js

@@ -28,6 +28,7 @@ export const fieldTypeToStore = {
     // Text store
     text: { storeType: 'text', valueColumn: 'value' },
     textArea: { storeType: 'text', valueColumn: 'value' },
+    code: { storeType: 'text', valueColumn: 'value' },
     select: { storeType: 'text', valueColumn: 'value' },
     // Numeric store
     integer: { storeType: 'numeric', valueColumn: 'value_integer' },

package/dist/storage/field-store-map.test.node.js

@@ -18,6 +18,7 @@ import { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, } from './fiel
 const VALUE_FIELD_TYPES = [
     'text',
     'textArea',
+    'code',
     'select',
     'integer',
     'float',

package/dist/utils/slugify-filename.d.ts

@@ -0,0 +1,50 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Context passed to a `FilenameSlugifierFn`.
+ *
+ * `collectionPath` - The collection receiving the upload. Lets an
+ *                    installation-supplied slugifier branch by collection
+ *                    if filename policies differ.
+ * `fieldName`      - The upload field's name within the collection.
+ * `mimeType`       - The uploaded file's MIME type.
+ */
+export type FilenameSlugifyContext = {
+    collectionPath: string;
+    fieldName: string;
+    mimeType: string;
+};
+/**
+ * A pure function that converts an uploaded file's **base name** (extension
+ * already split off) into a storage-safe slug. The extension is handled by
+ * the framework — lowercased and reattached after slugification — so
+ * implementations only see and return the base name.
+ *
+ * Registered installation-wide via `ServerConfig.uploads.filenameSlugifier`;
+ * the parallel of `ServerConfig.slugifier` for document paths. Must be
+ * synchronous and side-effect free. Return value is sanitised again by the
+ * storage provider as a safety net, but implementations should stay within
+ * `A–Z a–z 0–9 . _ -` to keep the slug authoritative.
+ */
+export type FilenameSlugifierFn = (basename: string, ctx: FilenameSlugifyContext) => string;
+/**
+ * Default filename slugifier — lowercases, replaces unsafe characters with
+ * hyphens, collapses runs, trims leading/trailing hyphens, and falls back
+ * to `'file'` for empty results. Mirrors the storage providers' own
+ * sanitisation rules so the default round-trips them unchanged.
+ */
+export declare const slugifyFilename: FilenameSlugifierFn;
+/**
+ * Resolve an uploaded file's stored filename: split the extension, apply the
+ * installation slugifier (or the default) to the base name, and reattach the
+ * lowercased extension. This runs in `uploadField` **before** the
+ * `beforeStore` hook chain, so hooks observe (and may override) the
+ * already-slugified name — the same ordering the previous fixed sanitiser
+ * had.
+ */
+export declare function resolveUploadFilename(originalFilename: string, slugifier: FilenameSlugifierFn | undefined, ctx: FilenameSlugifyContext): string;

package/dist/utils/slugify-filename.js

@@ -0,0 +1,36 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Default filename slugifier — lowercases, replaces unsafe characters with
+ * hyphens, collapses runs, trims leading/trailing hyphens, and falls back
+ * to `'file'` for empty results. Mirrors the storage providers' own
+ * sanitisation rules so the default round-trips them unchanged.
+ */
+export const slugifyFilename = (basename) => {
+    const safe = basename
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return safe || 'file';
+};
+/**
+ * Resolve an uploaded file's stored filename: split the extension, apply the
+ * installation slugifier (or the default) to the base name, and reattach the
+ * lowercased extension. This runs in `uploadField` **before** the
+ * `beforeStore` hook chain, so hooks observe (and may override) the
+ * already-slugified name — the same ordering the previous fixed sanitiser
+ * had.
+ */
+export function resolveUploadFilename(originalFilename, slugifier, ctx) {
+    const lastDot = originalFilename.lastIndexOf('.');
+    const ext = lastDot > 0 ? originalFilename.slice(lastDot).toLowerCase() : '';
+    const base = lastDot > 0 ? originalFilename.slice(0, lastDot) : originalFilename;
+    const slug = (slugifier ?? slugifyFilename)(base, ctx);
+    return `${slug || 'file'}${ext}`;
+}

package/dist/utils/slugify-filename.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/utils/slugify-filename.test.node.js

@@ -0,0 +1,50 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { resolveUploadFilename, slugifyFilename } from './slugify-filename.js';
+const ctx = { collectionPath: 'events', fieldName: 'attachment', mimeType: 'application/pdf' };
+describe('slugifyFilename (default)', () => {
+    it('lowercases and hyphenates unsafe characters', () => {
+        expect(slugifyFilename('Meeting Agenda (Final)', ctx)).toBe('meeting-agenda-final');
+    });
+    it('collapses hyphen runs and trims leading/trailing hyphens', () => {
+        expect(slugifyFilename('--Board -- Notes--', ctx)).toBe('board-notes');
+    });
+    it('falls back to "file" for empty results', () => {
+        expect(slugifyFilename('***', ctx)).toBe('file');
+    });
+});
+describe('resolveUploadFilename', () => {
+    it('slugifies the base name and lowercases the extension', () => {
+        expect(resolveUploadFilename('Meeting Agenda.PDF', undefined, ctx)).toBe('meeting-agenda.pdf');
+    });
+    it('handles filenames without an extension', () => {
+        expect(resolveUploadFilename('README', undefined, ctx)).toBe('readme');
+    });
+    it('treats a leading dot as part of the base name, not an extension', () => {
+        expect(resolveUploadFilename('.gitignore', undefined, ctx)).toBe('.gitignore');
+    });
+    it('only splits at the last dot', () => {
+        expect(resolveUploadFilename('archive.tar.gz', undefined, ctx)).toBe('archive.tar.gz');
+    });
+    it('applies a custom slugifier to the base name only', () => {
+        const shouty = (base) => base.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+        expect(resolveUploadFilename('Meeting Agenda.pdf', shouty, ctx)).toBe('MEETING_AGENDA.pdf');
+    });
+    it('passes the slugify context through to the custom slugifier', () => {
+        const seen = [];
+        resolveUploadFilename('photo.jpg', (base, c) => {
+            seen.push(c);
+            return base;
+        }, ctx);
+        expect(seen).toEqual([ctx]);
+    });
+    it('guards against a custom slugifier returning an empty string', () => {
+        expect(resolveUploadFilename('photo.jpg', () => '', ctx)).toBe('file.jpg');
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -81,7 +81,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "4.0.0"
+    "@byline/auth": "4.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",