@owlmeans/image-resource 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# @owlmeans/image-resource
+
+The **@owlmeans/image-resource** package provides specialized image management functionality for OwlMeans Common Libraries, extending the core storage functionality with image-specific operations and validation schemas for handling images in object storage systems like S3.
+
+## Purpose
+
+This package serves as an image-specific extension to the storage system, designed for:
+
+- **Image Storage Management**: Specialized handling of image files in object storage
+- **Image Metadata**: Enhanced metadata management specific to image files
+- **Validation Schemas**: AJV schemas for image data validation
+- **Type Safety**: TypeScript interfaces for image-related data structures
+- **Storage Integration**: Seamless integration with OwlMeans storage infrastructure
+
+## Key Concepts
+
+### Image-specific Storage
+Extends the basic file storage functionality with image-specific operations and metadata handling.
+
+### Type Extensions
+Provides specialized TypeScript interfaces that extend the base storage types for image-specific use cases.
+
+### Schema Validation
+Includes AJV schemas for validating image metadata and data structures.
+
+### Storage Abstraction
+Builds upon the storage-common package to provide higher-level image management capabilities.
+
+## Installation
+
+```bash
+npm install @owlmeans/image-resource
+```
+
+## API Reference
+
+### Types
+
+#### `ImageMeta`
+Metadata interface for stored images.
+
+```typescript
+interface ImageMeta extends StoredFileMeta {
+  // Extends base file metadata with image-specific properties
+}
+```
+
+#### `StoredImage`
+Interface for stored image files.
+
+```typescript
+interface StoredImage extends StoredFile {
+  // Extends base stored file interface for images
+}
+```
+
+#### `ImageData`
+Interface for image data with content.
+
+```typescript
+interface ImageData extends StoredFileWithData {
+  // Extends base file data interface for images
+}
+```
+
+### Validation Schemas
+
+#### `ImageMetaSchema`
+AJV schema for validating image metadata.
+
+```typescript
+const ImageMetaSchema: JSONSchemaType<ImageMeta>
+```
+
+#### `StoredImageSchema`
+AJV schema for validating stored image objects.
+
+```typescript
+const StoredImageSchema: JSONSchemaType<StoredImage>
+```
+
+#### `ImageDataSchema`
+AJV schema for validating image data with content.
+
+```typescript
+const ImageDataSchema: JSONSchemaType<ImageData>
+```
+
+## Usage Examples
+
+### Basic Image Validation
+
+```typescript
+import { ImageMetaSchema, StoredImageSchema, ImageDataSchema } from '@owlmeans/image-resource'
+import Ajv from 'ajv'
+
+const ajv = new Ajv()
+
+// Validate image metadata
+const validateImageMeta = ajv.compile(ImageMetaSchema)
+const isValidMeta = validateImageMeta(imageMetadata)
+
+// Validate stored image
+const validateStoredImage = ajv.compile(StoredImageSchema)
+const isValidImage = validateStoredImage(imageObject)
+
+// Validate image data
+const validateImageData = ajv.compile(ImageDataSchema)
+const isValidData = validateImageData(imageDataObject)
+```
+
+### Integration with Storage Systems
+
+```typescript
+import type { ImageMeta, StoredImage, ImageData } from '@owlmeans/image-resource'
+import { ImageMetaSchema } from '@owlmeans/image-resource'
+
+class ImageStorageService {
+  async storeImage(file: File, metadata: Partial<ImageMeta>): Promise<StoredImage> {
+    // Validate metadata
+    const validateMeta = ajv.compile(ImageMetaSchema)
+    if (!validateMeta(metadata)) {
+      throw new Error('Invalid image metadata')
+    }
+    
+    // Process and store image
+    const storedImage: StoredImage = {
+      id: generateId(),
+      filename: file.name,
+      contentType: file.type,
+      size: file.size,
+      ...metadata
+    }
+    
+    return storedImage
+  }
+  
+  async getImageData(imageId: string): Promise<ImageData> {
+    // Retrieve image with data
+    const imageData = await this.storage.getWithData(imageId)
+    
+    // Validate returned data
+    const validateData = ajv.compile(ImageDataSchema)
+    if (!validateData(imageData)) {
+      throw new Error('Invalid image data format')
+    }
+    
+    return imageData as ImageData
+  }
+}
+```
+
+### Type-safe Image Operations
+
+```typescript
+import type { ImageMeta, StoredImage } from '@owlmeans/image-resource'
+
+interface ImageProcessor {
+  processImage(image: StoredImage): Promise<StoredImage>
+  getImageMetadata(imageId: string): Promise<ImageMeta>
+  updateImageMetadata(imageId: string, metadata: Partial<ImageMeta>): Promise<void>
+}
+
+class BasicImageProcessor implements ImageProcessor {
+  async processImage(image: StoredImage): Promise<StoredImage> {
+    // Process the image (resize, compress, etc.)
+    return {
+      ...image,
+      // Updated properties after processing
+    }
+  }
+  
+  async getImageMetadata(imageId: string): Promise<ImageMeta> {
+    const metadata = await this.storage.getMetadata(imageId)
+    return metadata as ImageMeta
+  }
+  
+  async updateImageMetadata(imageId: string, metadata: Partial<ImageMeta>): Promise<void> {
+    await this.storage.updateMetadata(imageId, metadata)
+  }
+}
+```
+
+## Integration Patterns
+
+### Web Upload Handler
+
+```typescript
+import type { ImageData } from '@owlmeans/image-resource'
+import { ImageDataSchema } from '@owlmeans/image-resource'
+
+async function handleImageUpload(file: File): Promise<ImageData> {
+  // Create image data object
+  const imageData: ImageData = {
+    id: generateId(),
+    filename: file.name,
+    contentType: file.type,
+    size: file.size,
+    data: await file.arrayBuffer(),
+    uploadedAt: new Date(),
+    // Additional image-specific metadata
+  }
+  
+  // Validate before processing
+  const validate = ajv.compile(ImageDataSchema)
+  if (!validate(imageData)) {
+    throw new Error('Invalid image data')
+  }
+  
+  return imageData
+}
+```
+
+### Storage Resource Integration
+
+```typescript
+import { StorageResource } from '@owlmeans/storage-resource'
+import type { StoredImage } from '@owlmeans/image-resource'
+
+class ImageResource extends StorageResource<StoredImage> {
+  constructor() {
+    super({
+      schema: StoredImageSchema,
+      bucket: 'images',
+      // Image-specific configuration
+    })
+  }
+  
+  async uploadImage(file: File, metadata?: Partial<ImageMeta>): Promise<StoredImage> {
+    const imageData = await this.processFile(file)
+    return await this.store({
+      ...imageData,
+      ...metadata
+    })
+  }
+}
+```
+
+## Best Practices
+
+1. **Validation**: Always validate image data using provided schemas
+2. **Type Safety**: Use TypeScript interfaces for compile-time safety
+3. **Metadata Management**: Properly manage image-specific metadata
+4. **Integration**: Leverage with storage-common and storage-resource packages
+5. **Error Handling**: Implement proper error handling for validation failures
+
+## Dependencies
+
+This package depends on:
+- `@owlmeans/storage-common` - Core storage types and schemas
+- `ajv` - JSON schema validation
+
+## Related Packages
+
+- [`@owlmeans/storage-common`](../storage-common) - Core storage functionality
+- [`@owlmeans/storage-resource`](../storage-resource) - Storage resource management
+- [`@owlmeans/resource`](../resource) - Base resource management

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export * from './model.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,YAAY,CAAA"}

package/build/index.js

@@ -0,0 +1,2 @@
+export * from './model.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,YAAY,CAAA"}

package/build/model.d.ts

@@ -0,0 +1,6 @@
+import type { JSONSchemaType } from 'ajv';
+import type { ImageMeta, StoredImage, ImageData } from './types.js';
+export declare const ImageMetaSchema: JSONSchemaType<ImageMeta>;
+export declare const StoredImageSchema: JSONSchemaType<StoredImage>;
+export declare const ImageDataSchema: JSONSchemaType<ImageData>;
+//# sourceMappingURL=model.d.ts.map

package/build/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,KAAK,CAAA;AAEvC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEnE,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,SAAS,CAOrD,CAAA;AAED,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,WAAW,CAOzD,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,SAAS,CAOrD,CAAA"}

package/build/model.js

@@ -0,0 +1,26 @@
+import { StoredFileMetaSchema, StoredFileSchema, StoredFileWithDataSchema } from '@owlmeans/storage-common';
+export const ImageMetaSchema = {
+    type: 'object',
+    properties: {
+        ...StoredFileMetaSchema.properties,
+    },
+    required: [...StoredFileMetaSchema.required],
+    additionalProperties: false,
+};
+export const StoredImageSchema = {
+    type: 'object',
+    properties: {
+        ...StoredFileSchema.properties,
+    },
+    required: [...StoredFileSchema.required],
+    additionalProperties: false,
+};
+export const ImageDataSchema = {
+    type: 'object',
+    properties: {
+        ...StoredFileWithDataSchema.properties,
+    },
+    required: [...StoredFileWithDataSchema.required],
+    additionalProperties: false,
+};
+//# sourceMappingURL=model.js.map

package/build/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAG3G,MAAM,CAAC,MAAM,eAAe,GAA8B;IACxD,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,GAAG,oBAAoB,CAAC,UAAU;KACnC;IACD,QAAQ,EAAE,CAAC,GAAG,oBAAoB,CAAC,QAAQ,CAAC;IAC5C,oBAAoB,EAAE,KAAK;CAC5B,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAgC;IAC5D,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,GAAG,gBAAgB,CAAC,UAAU;KAC/B;IACD,QAAQ,EAAE,CAAC,GAAG,gBAAgB,CAAC,QAAQ,CAAC;IACxC,oBAAoB,EAAE,KAAK;CAC5B,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAA8B;IACxD,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,GAAG,wBAAwB,CAAC,UAAU;KACvC;IACD,QAAQ,EAAE,CAAC,GAAG,wBAAwB,CAAC,QAAQ,CAAC;IAChD,oBAAoB,EAAE,KAAK;CAC5B,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,8 @@
+import type { StoredFile, StoredFileMeta, StoredFileWithData } from '@owlmeans/storage-common';
+export interface ImageMeta extends StoredFileMeta {
+}
+export interface StoredImage extends StoredFile {
+}
+export interface ImageData extends StoredFileWithData {
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAE9F,MAAM,WAAW,SAAU,SAAQ,cAAc;CAChD;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;CAC9C;AAED,MAAM,WAAW,SAAU,SAAQ,kBAAkB;CACpD"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@owlmeans/image-resource",
+  "type": "module",
+  "version": "0.1.0",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 390 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "ajv": "*"
+  },
+  "dependencies": {
+    "@owlmeans/storage-resource": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.8",
+    "nodemon": "^3.1.7",
+    "typescript": "^5.6.3"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+
+export type * from './types.js'
+export * from './model.js'

package/src/model.ts

@@ -0,0 +1,30 @@
+import type {JSONSchemaType} from 'ajv'
+import { StoredFileMetaSchema, StoredFileSchema, StoredFileWithDataSchema } from '@owlmeans/storage-common'
+import type { ImageMeta, StoredImage, ImageData } from './types.js'
+
+export const ImageMetaSchema: JSONSchemaType<ImageMeta> = {
+  type: 'object',
+  properties: {
+    ...StoredFileMetaSchema.properties,
+  },
+  required: [...StoredFileMetaSchema.required],
+  additionalProperties: false,
+}
+
+export const StoredImageSchema: JSONSchemaType<StoredImage> = {
+  type: 'object',
+  properties: {
+    ...StoredFileSchema.properties,
+  },
+  required: [...StoredFileSchema.required],
+  additionalProperties: false,
+}
+
+export const ImageDataSchema: JSONSchemaType<ImageData> = {
+  type: 'object',
+  properties: {
+    ...StoredFileWithDataSchema.properties,
+  },
+  required: [...StoredFileWithDataSchema.required],
+  additionalProperties: false,
+}

package/src/types.ts

@@ -0,0 +1,11 @@
+
+import type { StoredFile, StoredFileMeta, StoredFileWithData } from '@owlmeans/storage-common'
+
+export interface ImageMeta extends StoredFileMeta {
+}
+
+export interface StoredImage extends StoredFile {
+}
+
+export interface ImageData extends StoredFileWithData {
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": [
+    "../tsconfig.default.json",
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/", /* Specify the root folder within your source files. */
+    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+    "moduleResolution": "Bundler",
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./*.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/model.ts","./src/types.ts"],"version":"5.6.3"}