@concord-consortium/object-storage 1.0.0-pre.0

package/README.md

@@ -0,0 +1,70 @@
+# @concord-consortium/object-storage
+
+A TypeScript library for object storage.
+
+## Installation
+
+```bash
+npm install @concord-consortium/object-storage
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createObjectStorage, ObjectStorageConfig } from '@concord-consortium/object-storage';
+
+const config: ObjectStorageConfig = { type: "demo", version: 1 };
+const storage = createObjectStorage(config);
+```
+
+### React Context Usage
+
+```typescript
+import { ObjectStorageProvider, useObjectStorage } from '@concord-consortium/object-storage';
+
+function App() {
+  const config = { type: "demo", version: 1 } as const;
+
+  return (
+    <ObjectStorageProvider config={config}>
+      <YourComponent />
+    </ObjectStorageProvider>
+  );
+}
+
+function YourComponent() {
+  const storage = useObjectStorage();
+
+  // Use storage methods
+  const handleAdd = async () => {
+    const id = await storage.add({ metadata: {}, data: {} });
+  };
+
+  return <div>Your component</div>;
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## License
+
+MIT

package/dist/demo-object-storage.d.ts

@@ -0,0 +1,61 @@
+import { DemoObjectStorageConfig, IObjectStorage, ObjectMetadata, ObjectData, StoredObject, ObjectWithId, MonitorCallback, DemonitorFunction } from './types';
+export declare class DemoObjectStorage implements IObjectStorage {
+    private config;
+    private objects;
+    private monitors;
+    constructor(config: DemoObjectStorageConfig);
+    /**
+     * Lists metadata documents for objects owned by the current user
+     */
+    listMine(): Promise<ObjectWithId[]>;
+    /**
+     * Lists metadata documents for objects linked to the current user
+     */
+    listLinked(): Promise<ObjectWithId[]>;
+    /**
+     * Lists metadata documents for objects associated with specific question IDs
+     */
+    list(questionIds: string[]): Promise<ObjectWithId[]>;
+    /**
+     * Monitors metadata documents for objects owned by the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorMine(callback: MonitorCallback): DemonitorFunction;
+    /**
+     * Monitors metadata documents for objects linked to the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorLinked(callback: MonitorCallback): DemonitorFunction;
+    /**
+     * Monitors metadata documents for objects associated with specific question IDs
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitor(questionIds: string[], callback: MonitorCallback): DemonitorFunction;
+    /**
+     * Adds both metadata and data documents for a new object
+     * Returns the generated object ID (nanoid)
+     */
+    add(object: StoredObject): Promise<string>;
+    /**
+     * Reads both metadata and data documents for an object
+     * Returns undefined if the object is not found
+     */
+    read(objectId: string): Promise<StoredObject | undefined>;
+    /**
+     * Reads only the metadata document for an object
+     * Returns undefined if the object is not found
+     */
+    readMetadata(objectId: string): Promise<ObjectMetadata | undefined>;
+    /**
+     * Reads only the data document for an object
+     * Returns undefined if the object is not found
+     */
+    readData(objectId: string): Promise<ObjectData | undefined>;
+    /**
+     * Notifies all active monitors of changes
+     */
+    private notifyMonitors;
+}

package/dist/demo-object-storage.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DemoObjectStorage = void 0;
+const nanoid_1 = require("nanoid");
+class DemoObjectStorage {
+    constructor(config) {
+        if (config.version !== 1) {
+            throw new Error(`Unsupported config version: ${config.version}. Expected version 1.`);
+        }
+        this.config = config;
+        this.objects = new Map();
+        this.monitors = new Map();
+    }
+    /**
+     * Lists metadata documents for objects owned by the current user
+     */
+    async listMine() {
+        return Array.from(this.objects.values());
+    }
+    /**
+     * Lists metadata documents for objects linked to the current user
+     */
+    async listLinked() {
+        // not applicable in demo storage
+        return [];
+    }
+    /**
+     * Lists metadata documents for objects associated with specific question IDs
+     */
+    async list(questionIds) {
+        // In demo mode, just return all objects
+        return Array.from(this.objects.values());
+    }
+    /**
+     * Monitors metadata documents for objects owned by the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorMine(callback) {
+        const key = 'mine';
+        if (!this.monitors.has(key)) {
+            this.monitors.set(key, []);
+        }
+        this.monitors.get(key).push(callback);
+        // Invoke callback immediately with current state
+        callback(Array.from(this.objects.values()));
+        return () => {
+            const callbacks = this.monitors.get(key);
+            if (callbacks) {
+                const index = callbacks.indexOf(callback);
+                if (index > -1) {
+                    callbacks.splice(index, 1);
+                }
+            }
+        };
+    }
+    /**
+     * Monitors metadata documents for objects linked to the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorLinked(callback) {
+        // not applicable in demo storage
+        callback([]);
+        return () => {
+            // no-op
+        };
+    }
+    /**
+     * Monitors metadata documents for objects associated with specific question IDs
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitor(questionIds, callback) {
+        const key = `monitor-${questionIds.join(',')}`;
+        if (!this.monitors.has(key)) {
+            this.monitors.set(key, []);
+        }
+        this.monitors.get(key).push(callback);
+        // Invoke callback immediately with current state
+        callback(Array.from(this.objects.values()));
+        return () => {
+            const callbacks = this.monitors.get(key);
+            if (callbacks) {
+                const index = callbacks.indexOf(callback);
+                if (index > -1) {
+                    callbacks.splice(index, 1);
+                }
+            }
+        };
+    }
+    /**
+     * Adds both metadata and data documents for a new object
+     * Returns the generated object ID (nanoid)
+     */
+    async add(object) {
+        const id = (0, nanoid_1.nanoid)();
+        const objectWithId = {
+            id,
+            metadata: object.metadata,
+            data: object.data
+        };
+        this.objects.set(id, objectWithId);
+        // Notify all monitors
+        this.notifyMonitors();
+        return id;
+    }
+    /**
+     * Reads both metadata and data documents for an object
+     * Returns undefined if the object is not found
+     */
+    async read(objectId) {
+        const obj = this.objects.get(objectId);
+        if (!obj) {
+            return undefined;
+        }
+        return {
+            metadata: obj.metadata,
+            data: obj.data
+        };
+    }
+    /**
+     * Reads only the metadata document for an object
+     * Returns undefined if the object is not found
+     */
+    async readMetadata(objectId) {
+        const obj = this.objects.get(objectId);
+        if (!obj) {
+            return undefined;
+        }
+        return obj.metadata;
+    }
+    /**
+     * Reads only the data document for an object
+     * Returns undefined if the object is not found
+     */
+    async readData(objectId) {
+        const obj = this.objects.get(objectId);
+        if (!obj) {
+            return undefined;
+        }
+        return obj.data;
+    }
+    /**
+     * Notifies all active monitors of changes
+     */
+    notifyMonitors() {
+        const allObjects = Array.from(this.objects.values());
+        this.monitors.forEach(callbacks => {
+            callbacks.forEach(callback => callback(allObjects));
+        });
+    }
+}
+exports.DemoObjectStorage = DemoObjectStorage;

package/dist/firebase-object-storage.d.ts

@@ -0,0 +1,52 @@
+import { FirebaseObjectStorageConfig, IObjectStorage, ObjectMetadata, ObjectData, StoredObject, ObjectWithId, MonitorCallback, DemonitorFunction } from './types';
+export declare class FirebaseObjectStorage implements IObjectStorage {
+    private config;
+    constructor(config: FirebaseObjectStorageConfig);
+    /**
+     * Lists metadata documents for objects owned by the current user
+     */
+    listMine(): Promise<ObjectWithId[]>;
+    /**
+     * Lists metadata documents for objects linked to the current user
+     */
+    listLinked(): Promise<ObjectWithId[]>;
+    /**
+     * Lists metadata documents for objects associated with specific question IDs
+     */
+    list(questionIds: string[]): Promise<ObjectWithId[]>;
+    /**
+     * Monitors metadata documents for objects owned by the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorMine(callback: MonitorCallback): DemonitorFunction;
+    /**
+     * Monitors metadata documents for objects linked to the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorLinked(callback: MonitorCallback): DemonitorFunction;
+    /**
+     * Monitors metadata documents for objects associated with specific question IDs
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitor(questionIds: string[], callback: MonitorCallback): DemonitorFunction;
+    /**
+     * Adds both metadata and data documents for a new object
+     * Returns the generated object ID (nanoid)
+     */
+    add(object: StoredObject): Promise<string>;
+    /**
+     * Reads both metadata and data documents for an object
+     */
+    read(objectId: string): Promise<StoredObject | undefined>;
+    /**
+     * Reads only the metadata document for an object
+     */
+    readMetadata(objectId: string): Promise<ObjectMetadata | undefined>;
+    /**
+     * Reads only the data document for an object
+     */
+    readData(objectId: string): Promise<ObjectData | undefined>;
+}

package/dist/firebase-object-storage.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirebaseObjectStorage = void 0;
+class FirebaseObjectStorage {
+    constructor(config) {
+        if (config.version !== 1) {
+            throw new Error(`Unsupported config version: ${config.version}. Expected version 1.`);
+        }
+        this.config = config;
+    }
+    /**
+     * Lists metadata documents for objects owned by the current user
+     */
+    async listMine() {
+        // TODO: Implement Firebase query for user's own objects
+        return [];
+    }
+    /**
+     * Lists metadata documents for objects linked to the current user
+     */
+    async listLinked() {
+        // TODO: Implement Firebase query for linked objects
+        return [];
+    }
+    /**
+     * Lists metadata documents for objects associated with specific question IDs
+     */
+    async list(questionIds) {
+        // TODO: Implement Firebase query for objects by question IDs
+        return [];
+    }
+    /**
+     * Monitors metadata documents for objects owned by the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorMine(callback) {
+        // TODO: Implement Firebase realtime listener for user's own objects
+        callback([]);
+        return () => {
+            // TODO: Implement cleanup
+        };
+    }
+    /**
+     * Monitors metadata documents for objects linked to the current user
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitorLinked(callback) {
+        // TODO: Implement Firebase realtime listener for linked objects
+        callback([]);
+        return () => {
+            // TODO: Implement cleanup
+        };
+    }
+    /**
+     * Monitors metadata documents for objects associated with specific question IDs
+     * Invokes callback at start and on any change
+     * Returns a function to stop monitoring
+     */
+    monitor(questionIds, callback) {
+        // TODO: Implement Firebase realtime listener for objects by question IDs
+        callback([]);
+        return () => {
+            // TODO: Implement cleanup
+        };
+    }
+    /**
+     * Adds both metadata and data documents for a new object
+     * Returns the generated object ID (nanoid)
+     */
+    async add(object) {
+        // TODO: Generate nanoid
+        // TODO: Add metadata document to Firebase
+        // TODO: Add data document to Firebase
+        const newObjectId = 'placeholder-id';
+        return newObjectId;
+    }
+    /**
+     * Reads both metadata and data documents for an object
+     */
+    async read(objectId) {
+        // TODO: Read metadata document from Firebase
+        // TODO: Read data document from Firebase
+        return {
+            metadata: {},
+            data: {}
+        };
+    }
+    /**
+     * Reads only the metadata document for an object
+     */
+    async readMetadata(objectId) {
+        // TODO: Read metadata document from Firebase
+        return {};
+    }
+    /**
+     * Reads only the data document for an object
+     */
+    async readData(objectId) {
+        // TODO: Read data document from Firebase
+        return {};
+    }
+}
+exports.FirebaseObjectStorage = FirebaseObjectStorage;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { DemoObjectStorage } from './demo-object-storage';
+export { FirebaseObjectStorage } from './firebase-object-storage';
+export { createObjectStorage } from './object-storage';
+export { ObjectStorageProvider, useObjectStorage } from './object-storage-context';
+export { IObjectStorage, ObjectStorageConfig, DemoObjectStorageConfig, FirebaseObjectStorageConfig, ObjectMetadata, ObjectData, StoredObject, ObjectWithId, MonitorCallback, DemonitorFunction } from './types';

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useObjectStorage = exports.ObjectStorageProvider = exports.createObjectStorage = exports.FirebaseObjectStorage = exports.DemoObjectStorage = void 0;
+var demo_object_storage_1 = require("./demo-object-storage");
+Object.defineProperty(exports, "DemoObjectStorage", { enumerable: true, get: function () { return demo_object_storage_1.DemoObjectStorage; } });
+var firebase_object_storage_1 = require("./firebase-object-storage");
+Object.defineProperty(exports, "FirebaseObjectStorage", { enumerable: true, get: function () { return firebase_object_storage_1.FirebaseObjectStorage; } });
+var object_storage_1 = require("./object-storage");
+Object.defineProperty(exports, "createObjectStorage", { enumerable: true, get: function () { return object_storage_1.createObjectStorage; } });
+var object_storage_context_1 = require("./object-storage-context");
+Object.defineProperty(exports, "ObjectStorageProvider", { enumerable: true, get: function () { return object_storage_context_1.ObjectStorageProvider; } });
+Object.defineProperty(exports, "useObjectStorage", { enumerable: true, get: function () { return object_storage_context_1.useObjectStorage; } });

package/dist/object-storage-context.d.ts

@@ -0,0 +1,17 @@
+import React, { ReactNode } from "react";
+import { ObjectStorageConfig, IObjectStorage } from './types';
+interface ObjectStorageProviderProps {
+    config?: ObjectStorageConfig;
+    children: ReactNode;
+}
+/**
+ * Provider component that creates and provides an ObjectStorage instance
+ * based on the supplied configuration
+ */
+export declare function ObjectStorageProvider({ config, children }: ObjectStorageProviderProps): React.JSX.Element;
+/**
+ * Hook to access the ObjectStorage instance from context
+ * Must be used within an ObjectStorageProvider
+ */
+export declare function useObjectStorage(): IObjectStorage;
+export {};

package/dist/object-storage-context.js

@@ -0,0 +1,59 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectStorageProvider = ObjectStorageProvider;
+exports.useObjectStorage = useObjectStorage;
+const react_1 = __importStar(require("react"));
+const object_storage_1 = require("./object-storage");
+const ObjectStorageContext = (0, react_1.createContext)(null);
+/**
+ * Provider component that creates and provides an ObjectStorage instance
+ * based on the supplied configuration
+ */
+function ObjectStorageProvider({ config, children }) {
+    const objectStorage = (0, react_1.useMemo)(() => (0, object_storage_1.createObjectStorage)(config), [config]);
+    return (react_1.default.createElement(ObjectStorageContext.Provider, { value: objectStorage }, children));
+}
+/**
+ * Hook to access the ObjectStorage instance from context
+ * Must be used within an ObjectStorageProvider
+ */
+function useObjectStorage() {
+    const context = (0, react_1.useContext)(ObjectStorageContext);
+    if (!context) {
+        throw new Error('useObjectStorage must be used within an ObjectStorageProvider');
+    }
+    return context;
+}

package/dist/object-storage.d.ts

@@ -0,0 +1,5 @@
+import { ObjectStorageConfig, IObjectStorage } from './types';
+/**
+ * Factory function to create the appropriate ObjectStorage instance based on config type
+ */
+export declare function createObjectStorage(config?: ObjectStorageConfig): IObjectStorage;

package/dist/object-storage.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createObjectStorage = createObjectStorage;
+const demo_object_storage_1 = require("./demo-object-storage");
+const firebase_object_storage_1 = require("./firebase-object-storage");
+/**
+ * Factory function to create the appropriate ObjectStorage instance based on config type
+ */
+function createObjectStorage(config) {
+    if (!config) {
+        throw new Error('ObjectStorageConfig is required to create an ObjectStorage instance');
+    }
+    switch (config.type) {
+        case "demo":
+            return new demo_object_storage_1.DemoObjectStorage(config);
+        case "firebase":
+            return new firebase_object_storage_1.FirebaseObjectStorage(config);
+        default:
+            // TypeScript exhaustiveness check
+            const _exhaustive = config;
+            throw new Error(`Unknown config type: ${_exhaustive.type}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export interface DemoObjectStorageConfig {
+    type: "demo";
+    version: 1;
+}
+export interface FirebaseObjectStorageConfig {
+    type: "firebase";
+    version: 1;
+}
+export type ObjectStorageConfig = DemoObjectStorageConfig | FirebaseObjectStorageConfig;
+export interface IObjectStorage {
+    listMine(): Promise<ObjectWithId[]>;
+    listLinked(): Promise<ObjectWithId[]>;
+    list(questionIds: string[]): Promise<ObjectWithId[]>;
+    monitorMine(callback: MonitorCallback): DemonitorFunction;
+    monitorLinked(callback: MonitorCallback): DemonitorFunction;
+    monitor(questionIds: string[], callback: MonitorCallback): DemonitorFunction;
+    add(object: StoredObject): Promise<string>;
+    read(objectId: string): Promise<StoredObject | undefined>;
+    readMetadata(objectId: string): Promise<ObjectMetadata | undefined>;
+    readData(objectId: string): Promise<ObjectData | undefined>;
+}
+export interface ObjectMetadata {
+    [key: string]: any;
+}
+export interface ObjectData {
+    [key: string]: any;
+}
+export interface StoredObject {
+    metadata: ObjectMetadata;
+    data: ObjectData;
+}
+export interface ObjectWithId extends StoredObject {
+    id: string;
+}
+export type MonitorCallback = (objects: ObjectWithId[]) => void;
+export type DemonitorFunction = () => void;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@concord-consortium/object-storage",
+  "version": "1.0.0-pre.0",
+  "description": "A TypeScript library for object storage",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build",
+    "publish": "npm publish"
+  },
+  "keywords": [
+    "object-storage",
+    "storage"
+  ],
+  "author": "Concord Consortium",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "nanoid": "^3.3.7"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/react": "^17.0.39",
+    "jest": "^29.5.0",
+    "react": "^17.0.2",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  }
+}