@grest-ts/file 0.0.5

package/src/GGFile.ts

@@ -0,0 +1,259 @@
+/**
+ * Unified file abstraction for Grest framework.
+ * Works across HTTP (multipart), WebSocket (base64), and tests (in-memory).
+ *
+ * Single consumption: buffer()/stream()/text() can only be called once.
+ * Use clone() if multiple reads are needed.
+ */
+export abstract class GGFile {
+    abstract readonly name: string;
+    abstract readonly mimeType: string;
+    abstract readonly size: number;
+
+    /**
+     * Whether the file content has been consumed.
+     * Once consumed, buffer()/stream()/text() will throw.
+     */
+    abstract readonly consumed: boolean;
+
+    /**
+     * Get the file content as a ReadableStream.
+     * Can only be called once per file instance.
+     * @throws Error if already consumed
+     */
+    abstract stream(): ReadableStream<Uint8Array>;
+
+    /**
+     * Get the file content as a Uint8Array.
+     * Can only be called once per file instance.
+     * @throws Error if already consumed
+     */
+    abstract buffer(): Promise<Uint8Array>;
+
+    /**
+     * Get the file content as a UTF-8 string.
+     * Can only be called once per file instance.
+     * @throws Error if already consumed
+     */
+    abstract text(): Promise<string>;
+
+    /**
+     * Create a copy of this file that can be consumed independently.
+     * Only works if the file hasn't been consumed yet.
+     * @throws Error if already consumed
+     */
+    abstract clone(): GGFile;
+
+    // ==================== Static Factory Methods ====================
+
+    /**
+     * Create a GGFile from a Uint8Array buffer.
+     */
+    static fromBuffer(data: Uint8Array, name: string, mimeType: string = 'application/octet-stream'): GGFile {
+        return new BufferGGFile(data, name, mimeType);
+    }
+
+    /**
+     * Create a GGFile from a string (encoded as UTF-8).
+     */
+    static fromString(content: string, name: string, mimeType: string = 'text/plain'): GGFile {
+        const encoder = new TextEncoder();
+        return new BufferGGFile(encoder.encode(content), name, mimeType);
+    }
+
+    /**
+     * Create a GGFile from a base64-encoded string.
+     * Used for WebSocket transport where files are sent as base64.
+     */
+    static fromBase64(base64: string, name: string, mimeType: string = 'application/octet-stream'): GGFile {
+        const binaryString = atob(base64);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+        }
+        return new BufferGGFile(bytes, name, mimeType);
+    }
+
+    /**
+     * Convert a GGFile to base64 string.
+     * Consumes the file.
+     */
+    static async toBase64(file: GGFile): Promise<string> {
+        const buffer = await file.buffer();
+        let binary = '';
+        for (let i = 0; i < buffer.length; i++) {
+            binary += String.fromCharCode(buffer[i]);
+        }
+        return btoa(binary);
+    }
+
+    /**
+     * Serialize a GGFile to JSON format for WebSocket transport.
+     * Consumes the file.
+     */
+    static async toJSON(file: GGFile): Promise<GGFileJSON> {
+        return {
+            __ggfile: true,
+            name: file.name,
+            mimeType: file.mimeType,
+            size: file.size,
+            data: await GGFile.toBase64(file),
+        };
+    }
+
+    /**
+     * Deserialize a GGFile from JSON format.
+     */
+    static fromJSON(json: GGFileJSON): GGFile {
+        if (!json.__ggfile) {
+            throw new Error('Invalid GGFile JSON: missing __ggfile marker');
+        }
+        return GGFile.fromBase64(json.data, json.name, json.mimeType);
+    }
+
+    /**
+     * Check if a value is a serialized GGFile JSON.
+     */
+    static isJSON(value: unknown): value is GGFileJSON {
+        return typeof value === 'object'
+            && value !== null
+            && '__ggfile' in value
+            && (value as GGFileJSON).__ggfile === true
+            && 'name' in value
+            && 'mimeType' in value
+            && 'size' in value
+            && 'data' in value;
+    }
+
+    /**
+     * Create a GGFile from a native browser File.
+     * Lazily reads the file content only when buffer()/stream()/text() is called.
+     */
+    static fromBrowserFile(file: File & { readonly name: string }): GGFile {
+        return new BrowserGGFile(file);
+    }
+}
+
+/**
+ * JSON serialization format for GGFile (used in WebSocket transport).
+ */
+export interface GGFileJSON {
+    __ggfile: true;
+    name: string;
+    mimeType: string;
+    size: number;
+    data: string;  // base64 encoded
+}
+
+/**
+ * In-memory implementation of GGFile.
+ * Used for tests and when file content is already fully buffered.
+ */
+export class BufferGGFile extends GGFile {
+    private _consumed = false;
+    private readonly data: Uint8Array;
+    readonly name: string;
+    readonly mimeType: string;
+
+    constructor(data: Uint8Array, name: string, mimeType: string = 'application/octet-stream') {
+        super();
+        this.data = data;
+        this.name = name;
+        this.mimeType = mimeType;
+    }
+
+    get size(): number {
+        return this.data.length;
+    }
+
+    get consumed(): boolean {
+        return this._consumed;
+    }
+
+    protected assertNotConsumed(): void {
+        if (this._consumed) {
+            throw new Error(`GGFile "${this.name}" has already been consumed. Use clone() if multiple reads are needed.`);
+        }
+    }
+
+    stream(): ReadableStream<Uint8Array> {
+        this.assertNotConsumed();
+        this._consumed = true;
+
+        const data = this.data;
+        return new ReadableStream<Uint8Array>({
+            start(controller) {
+                controller.enqueue(data);
+                controller.close();
+            }
+        });
+    }
+
+    async buffer(): Promise<Uint8Array> {
+        this.assertNotConsumed();
+        this._consumed = true;
+        return this.data;
+    }
+
+    async text(): Promise<string> {
+        this.assertNotConsumed();
+        this._consumed = true;
+        return new TextDecoder().decode(this.data);
+    }
+
+    clone(): GGFile {
+        this.assertNotConsumed();
+        return new BufferGGFile(new Uint8Array(this.data), this.name, this.mimeType);
+    }
+}
+
+/**
+ * Browser implementation of GGFile that wraps a native File/Blob.
+ * Lazily reads file content only when buffer()/stream()/text() is called.
+ */
+export class BrowserGGFile extends GGFile {
+    private _consumed = false;
+    readonly name: string;
+    readonly mimeType: string;
+    readonly size: number;
+
+    constructor(private readonly nativeFile: File & { readonly name: string }) {
+        super();
+        this.name = nativeFile.name;
+        this.mimeType = nativeFile.type || 'application/octet-stream';
+        this.size = nativeFile.size;
+    }
+
+    get consumed(): boolean {
+        return this._consumed;
+    }
+
+    private assertNotConsumed(): void {
+        if (this._consumed) {
+            throw new Error(`GGFile "${this.name}" has already been consumed. Use clone() if multiple reads are needed.`);
+        }
+    }
+
+    stream(): ReadableStream<Uint8Array> {
+        this.assertNotConsumed();
+        this._consumed = true;
+        return this.nativeFile.stream() as ReadableStream<Uint8Array>;
+    }
+
+    async buffer(): Promise<Uint8Array> {
+        this.assertNotConsumed();
+        this._consumed = true;
+        return new Uint8Array(await this.nativeFile.arrayBuffer());
+    }
+
+    async text(): Promise<string> {
+        this.assertNotConsumed();
+        this._consumed = true;
+        return this.nativeFile.text();
+    }
+
+    clone(): GGFile {
+        this.assertNotConsumed();
+        return new BrowserGGFile(this.nativeFile);
+    }
+}

package/src/IsFile.ts

@@ -0,0 +1,153 @@
+import {GGSchema, GGSchemaNonJsonDefinition, GGSchemaBinaryData, GGIssueInvalid, Opt} from "@grest-ts/schema";
+import type {GGIssuesList} from "@grest-ts/schema";
+import {BufferGGFile, GGFile} from "./GGFile";
+
+/**
+ * Definition for file schema.
+ */
+export interface FileDef extends GGSchemaNonJsonDefinition {
+    readonly type: 'file';
+    readonly accept?: readonly string[];
+    readonly maxSize?: number;
+}
+
+// ==================== Helper Functions ====================
+
+function isGGFileLike(value: unknown): value is GGFile {
+    return typeof value === 'object'
+        && value !== null
+        && 'name' in value
+        && 'mimeType' in value
+        && 'size' in value
+        && typeof (value as any).name === 'string'
+        && typeof (value as any).mimeType === 'string'
+        && typeof (value as any).size === 'number';
+}
+
+function matchesAccept(name: string, mimeType: string, accept?: readonly string[]): boolean {
+    if (!accept || accept.length === 0) return true;
+    for (const pattern of accept) {
+        if (pattern.startsWith('.')) {
+            if (name.toLowerCase().endsWith(pattern.toLowerCase())) return true;
+        } else if (pattern === '*/*') {
+            return true;
+        } else if (pattern.endsWith('/*')) {
+            if (mimeType.startsWith(pattern.slice(0, -1))) return true;
+        } else {
+            if (mimeType === pattern) return true;
+        }
+    }
+    return false;
+}
+
+// ==================== FileSchema ====================
+
+export class FileSchema<T extends GGFile | undefined | null = GGFile> extends GGSchema<T, FileDef> {
+
+    public static readonly typeError = new GGIssueInvalid("file.type", "Value must be a file");
+    public static readonly mimeTypeError = new GGIssueInvalid<{ accept: string }>("file.mimeType", "File type not accepted, expected: {accept}", {accept: "Accepted types"});
+    public static readonly maxSizeError = new GGIssueInvalid<{ max: number }>("file.maxSize", "File exceeds maximum size of {max} bytes", {max: "Maximum size"});
+
+    constructor(def: { type: 'file', accept?: readonly string[], maxSize?: number, optional?: boolean, nullable?: boolean }) {
+        const {accept, maxSize} = def;
+
+        const is = (value: unknown): value is GGFile => {
+            if (!isGGFileLike(value)) return false;
+            return matchesAccept(value.name, value.mimeType, accept) && (maxSize === undefined || value.size <= maxSize);
+        };
+
+        const isWithErrors = (value: unknown, issues: GGIssuesList, path: string): value is GGFile => {
+            if (!isGGFileLike(value)) {
+                return FileSchema.typeError.add(value, issues, path);
+            }
+            let valid = true;
+            if (!matchesAccept(value.name, value.mimeType, accept)) {
+                FileSchema.mimeTypeError.add(value, issues, path, {accept: accept?.join(', ') ?? '*/*'});
+                valid = false;
+            }
+            if (maxSize !== undefined && value.size > maxSize) {
+                FileSchema.maxSizeError.add(value, issues, path, {max: maxSize});
+                valid = false;
+            }
+            return valid;
+        };
+
+        const encodeToRaw = async (value: unknown, path: string): Promise<GGSchemaBinaryData> => {
+            const file = value as GGFile;
+            const buffer = await file.clone().buffer();
+            const blob = new Blob([buffer as unknown as Uint8Array<ArrayBuffer>], {type: file.mimeType});
+            return {path, blob, filename: file.name};
+        };
+
+        const decodeFromRaw = async (raw: GGSchemaBinaryData): Promise<GGFile> => {
+            const buffer = await raw.blob.arrayBuffer();
+            return new BufferGGFile(new Uint8Array(buffer), raw.filename || 'file', raw.blob.type);
+        };
+
+        super({...def, hasNonJsonData: true, is, isWithErrors, encodeToRaw, decodeFromRaw} as FileDef);
+    }
+
+    // ==================== Schema Methods ====================
+
+    get orUndefined(): FileSchema<T | undefined> & Opt {
+        return super.orUndefined as any;
+    }
+
+    get orNull(): FileSchema<T | null> {
+        return super.orNull as any;
+    }
+
+    protected derive<NewT extends GGFile | undefined | null = T>(changes: Partial<FileDef>): FileSchema<NewT> {
+        if (this.def.maxSize !== undefined && changes.maxSize !== undefined && changes.maxSize > this.def.maxSize) {
+            throw new Error(`Cannot raise maxSize from ${this.def.maxSize} to ${changes.maxSize}`);
+        }
+        return new FileSchema<NewT>({
+            type: 'file',
+            accept: changes.accept ?? this.def.accept,
+            maxSize: changes.maxSize ?? this.def.maxSize,
+            optional: changes.optional ?? this.def.optional,
+            nullable: changes.nullable ?? this.def.nullable
+        });
+    }
+
+    // ==================== File Constraints ====================
+
+    accept(...types: string[]): FileSchema<T> {
+        const combined = this.def.accept ? [...this.def.accept, ...types] : types;
+        return this.derive({accept: combined});
+    }
+
+    maxSize(bytes: number): FileSchema<T> {
+        return this.derive({maxSize: bytes});
+    }
+
+    // ==================== Static Shortcuts ====================
+
+    static image(opts?: { maxSize?: number }): FileSchema {
+        let s = new FileSchema({type: 'file', accept: ['image/*']});
+        return opts?.maxSize ? s.maxSize(opts.maxSize) : s;
+    }
+
+    static pdf(opts?: { maxSize?: number }): FileSchema {
+        let s = new FileSchema({type: 'file', accept: ['application/pdf']});
+        return opts?.maxSize ? s.maxSize(opts.maxSize) : s;
+    }
+
+    static any(opts?: { maxSize?: number }): FileSchema {
+        let s = new FileSchema({type: 'file'});
+        return opts?.maxSize ? s.maxSize(opts.maxSize) : s;
+    }
+
+    static video(opts?: { maxSize?: number }): FileSchema {
+        let s = new FileSchema({type: 'file', accept: ['video/*']});
+        return opts?.maxSize ? s.maxSize(opts.maxSize) : s;
+    }
+
+    static audio(opts?: { maxSize?: number }): FileSchema {
+        let s = new FileSchema({type: 'file', accept: ['audio/*']});
+        return opts?.maxSize ? s.maxSize(opts.maxSize) : s;
+    }
+}
+
+export const IsFile = new FileSchema({type: 'file'});
+export type tFile = typeof IsFile.infer;

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./GGFile";
+export * from "./IsFile";
+
+export {BufferGGFile, BrowserGGFile} from "./GGFile";

package/src/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "//": "THIS FILE IS GENERATED - DO NOT EDIT",
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "**/*"
+  ]
+}