@byline/core 4.1.0 → 4.2.0

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.1.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.1.0"
+    "@byline/auth": "4.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",