@byline/core 1.2.1 → 1.4.0

package/dist/@types/storage-types.d.ts

@@ -38,6 +38,21 @@ export interface UploadFileOptions {
      * Providers may use this to namespace storage paths.
      */
     collection?: string;
+    /**
+     * Explicit, fully-qualified storage path / object key the provider must
+     * write to verbatim. When set, providers MUST place the file at exactly
+     * this path — no UUID prefix, year/month rewrite, or `pathPrefix` injection.
+     *
+     * Used by the image-variant pipeline (`generateImageVariants`) to write
+     * sibling files alongside an already-stored original (e.g. so the
+     * `thumbnail` variant of `media/2026/05/abc-photo.jpg` lands at
+     * `media/2026/05/abc-photo-thumbnail.webp`).
+     *
+     * Always POSIX-style (forward slashes), no leading slash. Callers are
+     * responsible for sanitisation and collision-avoidance — providers do
+     * not second-guess the path when this is set.
+     */
+    targetStoragePath?: string;
 }
 /**
  * The pluggable file-storage interface.

package/dist/image/image-processor.d.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { ImageSize } from '../@types/collection-types.js';
+import type { IStorageProvider, StoredFileLocation } from '../@types/storage-types.js';
 import type { BylineLogger } from '../logger/index.js';
 export interface ImageMeta {
     width: number | null;
@@ -35,11 +36,16 @@ export declare function isBypassMimeType(mimeType: string): boolean;
  */
 export declare function extractImageMeta(buffer: Buffer, mimeType: string): Promise<ImageMeta>;
 /**
- * Generate the named image variants (sizes) defined in `UploadConfig.sizes`.
+ * Generate the named image variants (sizes) defined in `UploadConfig.sizes`
+ * and persist them through the configured `IStorageProvider`.
  *
  * - SVG and GIF files are skipped entirely (bypass types).
- * - Each variant is written as a sibling file to the original, using the
- *   naming convention: `<basename>-<variantName>.<ext>`
+ * - Each variant is uploaded as a sibling object to `storedFile.storagePath`,
+ *   using the naming convention: `<dir>/<basename>-<variantName>.<ext>`
+ *   (POSIX paths — both local filesystem keys and S3 object keys).
+ * - Variant bytes are produced in-memory by Sharp and written via
+ *   `storage.upload(buffer, { targetStoragePath })` — no direct filesystem
+ *   access, so the function is provider-agnostic.
  * - Returns an array of `ImageVariantResult` describing what was created.
  */
-export declare function generateImageVariants(sourceBuffer: Buffer, mimeType: string, absoluteOriginalPath: string, storageBaseDir: string, sizes: ImageSize[], logger?: BylineLogger): Promise<ImageVariantResult[]>;
+export declare function generateImageVariants(sourceBuffer: Buffer, mimeType: string, storedFile: StoredFileLocation, storage: IStorageProvider, sizes: ImageSize[], logger?: BylineLogger): Promise<ImageVariantResult[]>;

package/dist/image/image-processor.js

@@ -5,7 +5,6 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import fs from 'node:fs';
 import path from 'node:path';
 // Sharp ships its own types; no @types/sharp needed.
 import sharp from 'sharp';
@@ -67,30 +66,52 @@ function tryParseSvgDimensions(buffer) {
 // Variant generation
 // ---------------------------------------------------------------------------
 /**
- * Generate the named image variants (sizes) defined in `UploadConfig.sizes`.
+ * Map a Sharp output format keyword to the corresponding image MIME type.
+ * Unknown formats fall back to `application/octet-stream` — the storage
+ * provider will accept it; only the served `Content-Type` is affected.
+ */
+function mimeTypeForFormat(format) {
+    switch (format) {
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'png':
+            return 'image/png';
+        case 'webp':
+            return 'image/webp';
+        case 'avif':
+            return 'image/avif';
+        default:
+            return 'application/octet-stream';
+    }
+}
+/**
+ * Generate the named image variants (sizes) defined in `UploadConfig.sizes`
+ * and persist them through the configured `IStorageProvider`.
  *
  * - SVG and GIF files are skipped entirely (bypass types).
- * - Each variant is written as a sibling file to the original, using the
- *   naming convention: `<basename>-<variantName>.<ext>`
+ * - Each variant is uploaded as a sibling object to `storedFile.storagePath`,
+ *   using the naming convention: `<dir>/<basename>-<variantName>.<ext>`
+ *   (POSIX paths — both local filesystem keys and S3 object keys).
+ * - Variant bytes are produced in-memory by Sharp and written via
+ *   `storage.upload(buffer, { targetStoragePath })` — no direct filesystem
+ *   access, so the function is provider-agnostic.
  * - Returns an array of `ImageVariantResult` describing what was created.
  */
-export async function generateImageVariants(sourceBuffer, mimeType, absoluteOriginalPath, storageBaseDir, sizes, logger) {
+export async function generateImageVariants(sourceBuffer, mimeType, storedFile, storage, sizes, logger) {
     if (isBypassMimeType(mimeType) || sizes.length === 0) {
         return [];
     }
-    const originalExt = path.extname(absoluteOriginalPath);
-    const originalBase = path.basename(absoluteOriginalPath, originalExt);
-    const variantDir = path.dirname(absoluteOriginalPath);
+    // Storage paths are POSIX-style across providers; use `path.posix` so
+    // Windows local-fs hosts don't introduce backslashes into S3 object keys.
+    const sourcePath = storedFile.storagePath;
+    const originalExt = path.posix.extname(sourcePath);
+    const originalBase = path.posix.basename(sourcePath, originalExt);
+    const variantDir = path.posix.dirname(sourcePath);
     const variants = [];
     for (const size of sizes) {
         const outputFormat = size.format ?? 'webp';
-        const outputExt = `.${outputFormat}`;
-        const variantFilename = `${originalBase}-${size.name}${outputExt}`;
-        const variantAbsolutePath = path.join(variantDir, variantFilename);
-        // Derive the storage-relative path (relative to storageBaseDir).
-        const variantStoragePath = path
-            .relative(storageBaseDir, variantAbsolutePath)
-            .replace(/\\/g, '/');
+        const variantFilename = `${originalBase}-${size.name}.${outputFormat}`;
+        const variantStoragePath = variantDir === '.' ? variantFilename : `${variantDir}/${variantFilename}`;
         try {
             let pipeline = sharp(sourceBuffer);
             const resizeOptions = {
@@ -118,9 +139,13 @@ export async function generateImageVariants(sourceBuffer, mimeType, absoluteOrig
                     pipeline = pipeline.webp({ quality: size.quality ?? 85 });
             }
             const variantBuffer = await pipeline.toBuffer();
-            fs.mkdirSync(path.dirname(variantAbsolutePath), { recursive: true });
-            await fs.promises.writeFile(variantAbsolutePath, variantBuffer);
             const sharpMeta = await sharp(variantBuffer).metadata();
+            await storage.upload(variantBuffer, {
+                filename: variantFilename,
+                mimeType: mimeTypeForFormat(outputFormat),
+                size: variantBuffer.byteLength,
+                targetStoragePath: variantStoragePath,
+            });
             variants.push({
                 name: size.name,
                 storagePath: variantStoragePath,

package/dist/query/parse-where.d.ts

@@ -75,6 +75,13 @@ declare const DOCUMENT_SORT_COLUMNS: Record<string, string>;
  * are resolved into `RelationFilter` entries; otherwise only
  * direct/operator predicates against the relation's own
  * `target_document_id` are emitted.
+ *
+ * Reserved-key rules inside a nested sub-clause: `status` and `path`
+ * downshift to `DocumentColumnFilter` entries against the target
+ * version's `document_versions` columns (the adapter wires these to
+ * `td${depth}.status` / `td${depth}.path` via the inner relation scope);
+ * `query` is dropped with a debug log because text search has no
+ * sensible composition through a relation hop.
  */
 export declare function parseWhere(where: WhereClause | undefined, definition: CollectionDefinition, ctx?: ParseContext): Promise<ParsedWhere>;
 /**

package/dist/query/parse-where.js

@@ -31,6 +31,13 @@ const DOCUMENT_SORT_COLUMNS = {
  * are resolved into `RelationFilter` entries; otherwise only
  * direct/operator predicates against the relation's own
  * `target_document_id` are emitted.
+ *
+ * Reserved-key rules inside a nested sub-clause: `status` and `path`
+ * downshift to `DocumentColumnFilter` entries against the target
+ * version's `document_versions` columns (the adapter wires these to
+ * `td${depth}.status` / `td${depth}.path` via the inner relation scope);
+ * `query` is dropped with a debug log because text search has no
+ * sensible composition through a relation hop.
  */
 export async function parseWhere(where, definition, ctx) {
     return parseWhereInternal(where, definition, ctx, { isNested: false, inCombinator: false });
@@ -57,10 +64,15 @@ export function mergePredicates(hookPredicate, userWhere) {
     return { $and: [hookPredicate, userWhere] };
 }
 /**
- * Recursion entry point. `isNested: true` disables the top-level reserved
- * keys (`status`, `query`, `path`) so that on a nested sub-where, those
- * names resolve as ordinary fields on the target collection (where `path`
- * and `status` are typically real text fields).
+ * Recursion entry point. `isNested: true` rewires the document-level
+ * reserved keys: `status` / `path` downshift to `DocumentColumnFilter`
+ * entries against the target version's columns (the adapter resolves
+ * those via the inner relation scope, e.g. `td${depth}.status`); `query`
+ * is dropped with a debug log because text search has no sensible
+ * composition through a relation hop. Reserved keys still take precedence
+ * over field lookups — a target collection that happens to declare a
+ * `path` or `status` field will not see those clauses resolve as field
+ * filters; rename the offending field if that conflict matters.
  */
 async function parseWhereInternal(where, definition, ctx, { isNested, inCombinator }) {
     const result = { filters: [] };
@@ -134,65 +146,82 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
             continue;
         }
         // --- Document-level reserved keys --------------------------------------
-        // At the top level (not nested in a relation, not inside a combinator)
-        // these keys map to direct adapter scalar parameters
-        // (`ParsedWhere.status` / `query` / `pathFilter`) which compile to the
-        // outermost WHERE clause. Inside a combinator that mapping no longer
-        // composes — the predicate needs to OR with siblings, which the scalar
-        // parameter form cannot express — so `status` / `path` downshift to a
-        // `DocumentColumnFilter` and `query` is dropped (text search has no
-        // sensible OR-composing form here).
-        if (!isNested) {
-            if (key === 'status') {
-                if (inCombinator) {
-                    const parsed = normaliseToOperator(rawValue);
-                    if (parsed) {
-                        result.filters.push({
-                            kind: 'docColumn',
-                            column: 'status',
-                            operator: parsed.operator,
-                            value: parsed.value === null ? null : String(parsed.value),
-                        });
-                    }
-                    continue;
-                }
-                if (typeof rawValue === 'string') {
-                    result.status = rawValue;
+        // `status` / `path` / `query` are reserved on every collection — they
+        // never resolve to a field of the same name (no field-shadow exception),
+        // mirroring the consumer-intuitive rule that these names refer to the
+        // document version's metadata columns.
+        //
+        // Where they compile depends on scope:
+        //
+        //   • Top level (not nested in a relation, not inside a combinator):
+        //     map to direct adapter scalar parameters
+        //     (`ParsedWhere.status` / `query` / `pathFilter`) which compile to
+        //     the outermost WHERE clause.
+        //
+        //   • Inside a combinator, OR inside a relation sub-clause: the scalar-
+        //     parameter mapping no longer composes (the predicate needs to OR
+        //     with siblings, or anchor against the *target's* doc version), so
+        //     `status` / `path` downshift to a `DocumentColumnFilter`. The SQL
+        //     compiler reads `outerScope.status` / `outerScope.path`, which the
+        //     adapter rewires per-scope (`d.path` at the top level,
+        //     `td${depth}.path` inside a relation hop).
+        //
+        //   • `query` is dropped with a debug log in both downshift cases —
+        //     text search has no sensible OR-composing form, and a per-target
+        //     EXISTS over `store_text` is intentionally deferred.
+        if (key === 'status') {
+            if (isNested || inCombinator) {
+                const parsed = normaliseToOperator(rawValue);
+                if (parsed) {
+                    result.filters.push({
+                        kind: 'docColumn',
+                        column: 'status',
+                        operator: parsed.operator,
+                        value: parsed.value === null ? null : String(parsed.value),
+                    });
                 }
                 continue;
             }
-            if (key === 'query') {
-                if (inCombinator) {
-                    ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a combinator — text search does not compose with OR/AND');
-                    continue;
-                }
-                if (typeof rawValue === 'string') {
-                    result.query = rawValue;
-                }
+            if (typeof rawValue === 'string') {
+                result.status = rawValue;
+            }
+            continue;
+        }
+        if (key === 'query') {
+            if (isNested) {
+                ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a relation sub-clause — text search does not compose through a relation hop');
                 continue;
             }
-            if (key === 'path') {
-                if (inCombinator) {
-                    const parsed = normaliseToOperator(rawValue);
-                    if (parsed) {
-                        result.filters.push({
-                            kind: 'docColumn',
-                            column: 'path',
-                            operator: parsed.operator,
-                            value: parsed.value === null ? null : String(parsed.value),
-                        });
-                    }
-                    continue;
-                }
+            if (inCombinator) {
+                ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a combinator — text search does not compose with OR/AND');
+                continue;
+            }
+            if (typeof rawValue === 'string') {
+                result.query = rawValue;
+            }
+            continue;
+        }
+        if (key === 'path') {
+            if (isNested || inCombinator) {
                 const parsed = normaliseToOperator(rawValue);
                 if (parsed) {
-                    result.pathFilter = {
+                    result.filters.push({
+                        kind: 'docColumn',
+                        column: 'path',
                         operator: parsed.operator,
-                        value: String(parsed.value),
-                    };
+                        value: parsed.value === null ? null : String(parsed.value),
+                    });
                 }
                 continue;
             }
+            const parsed = normaliseToOperator(rawValue);
+            if (parsed) {
+                result.pathFilter = {
+                    operator: parsed.operator,
+                    value: String(parsed.value),
+                };
+            }
+            continue;
         }
         // --- Field-level keys --------------------------------------------------
         const field = definition.fields.find((f) => f.name === key);
@@ -226,11 +255,11 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                 isNested: true,
                 inCombinator: false,
             });
-            // Flatten nested: only field-level / relation-level conditions make
-            // sense inside a relation subclause. Document-level keys (status,
-            // path, query) on the target are deliberately out of scope for this
-            // first phase — they can be added later by promoting them into
-            // the nested filter list here.
+            // Splice nested filters straight in. The nested parse runs with
+            // `isNested: true`, which promotes `status` / `path` into
+            // `DocumentColumnFilter` entries the adapter resolves against the
+            // target version's columns (`td${depth}.status` / `td${depth}.path`)
+            // via the inner relation scope. `query` is dropped one level up.
             result.filters.push({
                 kind: 'relation',
                 fieldName: key,

package/dist/query/parse-where.test.node.js

@@ -40,7 +40,11 @@ const categoriesCollection = defineCollection({
     }),
     fields: [
         { name: 'name', type: 'text', label: 'Name', localized: true },
-        { name: 'path', type: 'text', label: 'Path' },
+        // `slug`, not `path` — `path` is a reserved key that resolves to the
+        // target version's `document_versions.path` column inside a nested
+        // sub-clause (same precedence as the top level), so a real `path`
+        // field would be unreachable through the where clause.
+        { name: 'slug', type: 'text', label: 'Slug' },
         {
             name: 'parent',
             type: 'relation',
@@ -220,8 +224,8 @@ describe('parseWhere', () => {
             value: ['cat-a', 'cat-b'],
         });
     });
-    it('should emit a RelationFilter for a nested plain-object sub-where', async () => {
-        const result = await parseWhere({ category: { path: 'news' } }, testCollection, ctx);
+    it('should emit a RelationFilter for a nested plain-object sub-where (field key)', async () => {
+        const result = await parseWhere({ category: { slug: 'news' } }, testCollection, ctx);
         expect(result.filters).toHaveLength(1);
         expect(result.filters[0]).toEqual({
             kind: 'relation',
@@ -230,7 +234,7 @@ describe('parseWhere', () => {
             nested: [
                 {
                     kind: 'field',
-                    fieldName: 'path',
+                    fieldName: 'slug',
                     storeType: 'text',
                     valueColumn: 'value',
                     operator: '$eq',
@@ -239,6 +243,55 @@ describe('parseWhere', () => {
             ],
         });
     });
+    it('promotes `path` inside a nested sub-where to a DocumentColumnFilter', async () => {
+        // Reserved-key precedence: `path` inside a relation sub-clause maps to
+        // the target version's `document_versions.path` column, never to a
+        // field of the same name. The adapter wires it to `td${depth}.path`
+        // via the inner relation scope.
+        const result = await parseWhere({ category: { path: 'news' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'category',
+            targetCollectionId: 'id-test-categories',
+            nested: [
+                {
+                    kind: 'docColumn',
+                    column: 'path',
+                    operator: '$eq',
+                    value: 'news',
+                },
+            ],
+        });
+    });
+    it('promotes `status` inside a nested sub-where to a DocumentColumnFilter', async () => {
+        const result = await parseWhere({ category: { status: 'draft' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'category',
+            targetCollectionId: 'id-test-categories',
+            nested: [
+                {
+                    kind: 'docColumn',
+                    column: 'status',
+                    operator: '$eq',
+                    value: 'draft',
+                },
+            ],
+        });
+    });
+    it('drops `query` inside a nested sub-where (no nested filter emitted)', async () => {
+        // Same rationale as `query` inside a combinator: text search has no
+        // sensible composition through a relation hop.
+        const result = await parseWhere({ category: { query: 'news' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        const relation = result.filters[0];
+        expect(relation?.kind).toBe('relation');
+        if (relation?.kind !== 'relation')
+            return;
+        expect(relation.nested).toEqual([]);
+    });
     it('should support operator objects inside a nested sub-where', async () => {
         const result = await parseWhere({ category: { name: { $contains: 'news' } } }, testCollection, ctx);
         const relation = result.filters[0];
@@ -257,7 +310,7 @@ describe('parseWhere', () => {
         ]);
     });
     it('should recurse into multi-hop relation sub-wheres', async () => {
-        const result = await parseWhere({ category: { parent: { path: 'news' } } }, testCollection, ctx);
+        const result = await parseWhere({ category: { parent: { slug: 'news' } } }, testCollection, ctx);
         const top = result.filters[0];
         expect(top?.kind).toBe('relation');
         if (top?.kind !== 'relation')
@@ -274,7 +327,7 @@ describe('parseWhere', () => {
         expect(inner.nested).toEqual([
             {
                 kind: 'field',
-                fieldName: 'path',
+                fieldName: 'slug',
                 storeType: 'text',
                 valueColumn: 'value',
                 operator: '$eq',
@@ -282,6 +335,26 @@ describe('parseWhere', () => {
             },
         ]);
     });
+    it('recurses multi-hop with the doc-column form (target.path at depth 2)', async () => {
+        const result = await parseWhere({ category: { parent: { path: 'news' } } }, testCollection, ctx);
+        const top = result.filters[0];
+        expect(top?.kind).toBe('relation');
+        if (top?.kind !== 'relation')
+            return;
+        expect(top.nested).toHaveLength(1);
+        const inner = top.nested[0];
+        expect(inner?.kind).toBe('relation');
+        if (inner?.kind !== 'relation')
+            return;
+        expect(inner.nested).toEqual([
+            {
+                kind: 'docColumn',
+                column: 'path',
+                operator: '$eq',
+                value: 'news',
+            },
+        ]);
+    });
     it('should skip nested sub-where when ctx is not provided', async () => {
         const result = await parseWhere({ category: { path: 'news' } }, testCollection);
         expect(result.filters).toEqual([]);
@@ -526,6 +599,11 @@ describe('parseWhere — combinators', () => {
         expect(result.filters).toEqual([]);
     });
     it('parses combinators inside a nested relation sub-where', async () => {
+        // Inside the nested sub-where: `name` is a real field on the target
+        // (resolves to a FieldFilter) and `path` is a reserved key that
+        // downshifts to a `DocumentColumnFilter` against the target version's
+        // path column. Inside an `$or` either side composes — the OR is
+        // emitted as a CombinatorFilter wrapping both children.
         const result = await parseWhere({
             category: {
                 $or: [{ name: 'News' }, { path: 'announcements' }],
@@ -541,7 +619,7 @@ describe('parseWhere — combinators', () => {
             kind: 'or',
             children: [
                 { kind: 'field', fieldName: 'name' },
-                { kind: 'field', fieldName: 'path' },
+                { kind: 'docColumn', column: 'path', operator: '$eq', value: 'announcements' },
             ],
         });
     });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.2.1"
+    "@byline/auth": "1.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",