The minimalistic document archiving platform.
refactor(storage): add expression fallbacks (#1526)
Corentin Thomasset5c4becd8564e
diff --git a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.definitions.ts b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.definitions.tsindex 9a03302d..8c185be2 100644--- a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.definitions.ts+++ b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.definitions.ts@@ -1,4 +1,5 @@import type {+ StoragePatternExpressionDefinition,StoragePatternExpressionTransformer,StoragePatternInterpolationContext,} from './storage-pattern.types';@@ -6,20 +7,19 @@ import { formatDate, isValidDate } from '../../shared/date';import { generateRandomString } from '../../shared/random/random.services';import { ensureSafeFileName } from '../documents.models';-export const expressionsDefinitions: Record<- string,- (context: StoragePatternInterpolationContext) => string-> = {- 'document.id': (context) => context.documentId,- 'document.name': (context) => ensureSafeFileName(context.documentName),- 'organization.id': (context) => context.organizationId,- 'currentDate': (context) => context.now.toISOString(),- 'random': () => generateRandomString({ length: 8 }),+export const expressionsDefinitions: Record<string, StoragePatternExpressionDefinition> = {+ 'document.id': { resolve: (context) => context.documentId },+ 'document.name': { resolve: (context) => ensureSafeFileName(context.documentName) },+ 'organization.id': { resolve: (context) => context.organizationId },+ 'currentDate': { resolve: (context) => context.now.toISOString() },+ 'random': { resolve: () => generateRandomString({ length: 8 }) },...['yyyy', 'MM', 'dd', 'HH', 'mm', 'ss', 'SSS'].reduce((acc, token) => ({...acc,- [`currentDate.${token}`]: (context: StoragePatternInterpolationContext) =>- formatDate(context.now, `{${token}}`),+ [`currentDate.${token}`]: {+ resolve: (context: StoragePatternInterpolationContext) =>+ formatDate(context.now, `{${token}}`),+ },}),{},),diff --git a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.test.ts b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.test.tsindex 12aa0c7c..f0fd48af 100644--- a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.test.ts+++ b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.test.ts@@ -1,7 +1,103 @@+import type { StoragePatternInterpolationContext } from './storage-pattern.types';import { describe, expect, test } from 'vitest';-import { tokenizeStringArguments } from './storage-pattern.models';+import {+ evaluateStoragePatternExpression,+ tokenizeStringArguments,+} from './storage-pattern.models';describe('storage-pattern models', () => {+ describe('evaluateStoragePatternExpression', () => {+ const context: StoragePatternInterpolationContext = {+ documentId: 'doc_012345678901234567890123',+ documentName: 'My Document.pdf',+ organizationId: 'org_012345678901234567890123',+ now: new Date('2025-05-15T12:34:56.789Z'),+ };++ test('a null value uses the fallback without formatting it as a date', () => {+ expect(+ evaluateStoragePatternExpression({+ expressionDefinition: { resolve: () => null, fallback: 'no-date' },+ context,+ transformerParts: ['formatDate "{yyyy}"', 'uppercase'],+ }),+ ).toEqual('no-date');+ });++ test('an undefined value uses the fallback without transformers', () => {+ expect(+ evaluateStoragePatternExpression({+ expressionDefinition: { resolve: () => undefined, fallback: 'unknown' },+ context,+ transformerParts: [],+ }),+ ).toEqual('unknown');+ });++ test('an empty string uses the fallback', () => {+ expect(+ evaluateStoragePatternExpression({+ expressionDefinition: { resolve: () => '', fallback: 'unknown' },+ context,+ transformerParts: ['padStart 10 0'],+ }),+ ).toEqual('unknown');+ });++ test('a present value is transformed instead of using the fallback', () => {+ expect(+ evaluateStoragePatternExpression({+ expressionDefinition: {+ resolve: ({ now }) => now.toISOString(),+ fallback: 'no-date',+ },+ context,+ transformerParts: ['formatDate {yyyy}', 'padStart 6 0'],+ }),+ ).toEqual('002025');+ });++ test('an explicitly empty fallback is preserved', () => {+ expect(+ evaluateStoragePatternExpression({+ expressionDefinition: { resolve: () => null, fallback: '' },+ context,+ transformerParts: [],+ }),+ ).toEqual('');+ });++ test('a missing value without a fallback throws an error', () => {+ expect(() =>+ evaluateStoragePatternExpression({+ expressionDefinition: { resolve: () => null },+ context,+ transformerParts: [],+ }),+ ).toThrow('Expression resolved to an empty value');+ });++ test('unknown transformers are rejected even when the value is missing', () => {+ expect(() =>+ evaluateStoragePatternExpression({+ expressionDefinition: { resolve: () => null, fallback: 'no-date' },+ context,+ transformerParts: ['unknownTransformer'],+ }),+ ).toThrow('Unknown transformer: unknownTransformer');+ });++ test('a fallback does not hide an invalid date', () => {+ expect(() =>+ evaluateStoragePatternExpression({+ expressionDefinition: { resolve: () => 'invalid-date', fallback: 'no-date' },+ context,+ transformerParts: ['formatDate {yyyy}'],+ }),+ ).toThrow('Invalid date value: invalid-date');+ });+ });+describe('tokenizeStringArguments', () => {test('given a string of space-separated arguments, split them into an array', () => {expect(tokenizeStringArguments({ argumentsString: 'arg1 arg2 arg3' })).to.eql([diff --git a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.ts b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.tsindex 835704a2..e2a8d116 100644--- a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.ts+++ b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.models.ts@@ -1,4 +1,54 @@+import type {+ StoragePatternExpressionDefinition,+ StoragePatternInterpolationContext,+} from './storage-pattern.types';import { isNilOrEmptyString } from '../../shared/utils';+import { expressionTransformers } from './storage-pattern.definitions';++export function evaluateStoragePatternExpression({+ expressionDefinition,+ context,+ transformerParts,+}: {+ expressionDefinition: StoragePatternExpressionDefinition;+ context: StoragePatternInterpolationContext;+ transformerParts: string[];+}): string {+ const value = transformerParts.reduce((value, transformerPart) => {+ const [transformerRawName, ...transformerArgsParts] = transformerPart.split(' ');+ const transformerName = transformerRawName?.trim();+ const argumentsString = transformerArgsParts.join(' ').trim();++ if (isNilOrEmptyString(transformerName)) {+ throw new Error('Transformer name cannot be empty');+ }++ const transformer = expressionTransformers[transformerName];++ if (!transformer) {+ throw new Error(`Unknown transformer: ${transformerName}`);+ }++ // Preserve missing values until the fallback is applied, but still validate transformers.+ if (isNilOrEmptyString(value)) {+ return value;+ }++ const transformerArguments = tokenizeStringArguments({ argumentsString });++ return transformer({ value, args: transformerArguments });+ }, expressionDefinition.resolve(context));++ if (isNilOrEmptyString(value)) {+ if (expressionDefinition.fallback === undefined) {+ throw new Error('Expression resolved to an empty value');+ }++ return expressionDefinition.fallback;+ }++ return value;+}export function tokenizeStringArguments({argumentsString,diff --git a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.types.ts b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.types.tsindex 6ac749b1..5b785632 100644--- a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.types.ts+++ b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.types.ts@@ -7,6 +7,11 @@ export type StoragePatternInterpolationContext = {now: Date;};+export type StoragePatternExpressionDefinition = {+ resolve: (context: StoragePatternInterpolationContext) => string | null | undefined;+ fallback?: string;+};+export type StoragePatternExpressionTransformer = (args: {value: unknown;args?: string[];diff --git a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.usecases.ts b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.usecases.tsindex 75b13556..c2623119 100644--- a/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.usecases.ts+++ b/apps/papra-server/src/modules/documents/storage-patterns/storage-pattern.usecases.ts@@ -2,8 +2,8 @@ import type { StoragePatternInterpolationContext } from './storage-pattern.typesimport { castError } from '@corentinth/chisels';import { isNil, isNilOrEmptyString } from '../../shared/utils';import { DUMMY_DOCUMENT_ID, DUMMY_ORGANIZATION_ID } from './storage-pattern.constants';-import { expressionsDefinitions, expressionTransformers } from './storage-pattern.definitions';-import { tokenizeStringArguments } from './storage-pattern.models';+import { expressionsDefinitions } from './storage-pattern.definitions';+import { evaluateStoragePatternExpression } from './storage-pattern.models';export function buildStorageKey({storageKeyPattern,@@ -26,36 +26,14 @@ export function buildStorageKey({throw new Error(`Unknown expression: ${expression}`);}- const expressionBuilder = expressionsDefinitions[expression];+ const expressionDefinition = expressionsDefinitions[expression];- if (!expressionBuilder) {+ if (!expressionDefinition) {// This should never happen because of the check above, but for type safety- throw new Error(`No builder found for expression: ${expression}`);+ throw new Error(`No definition found for expression: ${expression}`);}- const baseValue = expressionBuilder(context);-- if (transformerParts.length === 0) {- return String(baseValue);- }-- return transformerParts.reduce((value, transformerPart) => {- const [transformerRawName, ...transformerArgsParts] = transformerPart.split(' ');-- const transformerName = transformerRawName?.trim();- const argumentsString = transformerArgsParts.join(' ').trim();-- const transformer =- expressionTransformers[transformerName as keyof typeof expressionTransformers];-- if (!transformer) {- throw new Error(`Unknown transformer: ${transformerName}`);- }-- const transformerArguments = tokenizeStringArguments({ argumentsString });-- return transformer({ value, args: transformerArguments });- }, baseValue);+ return evaluateStoragePatternExpression({ expressionDefinition, context, transformerParts });});return { storageKey };