Skip to content

armgit / papra

Public Imported from GitHub
0

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.types
import { 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 };