Added documentation

packages/core-v2/examples.md

@@ -124,6 +124,33 @@ const entities = Object.values(aggregatorView.getEntities()).map(aggregated => a
 console.log(await generate(entities));
 ```
 
+# UC03
+
+```ts
+import {BackendPackageService} from "@dataspecer/core-v2/project";
+import {httpFetch} from "@dataspecer/core/io/fetch/fetch-nodejs"; // or replace nodejs with browser
+
+const service = new BackendPackageService(BACKEND_URL, httpFetch);
+const root = await service.getPackage("cme-root"); // Just a name of the root package for your application
+
+console.log(root.subPackages.map(p => `${p.id}: ${p.name.cs}`));
+
+// Create a new package
+const pckg = await service.createPackage("cme-root", {
+    name: {cs: "My new project"}
+});
+
+// Tell models to be part of the package
+await service.updateSemanticModelPackageModels(pckg.id, models);
+
+// You can modify individual models as you wish
+
+// You can close the application
+
+// To restore models use
+const models = await service.constructSemanticModelPackageModels(packg.id);
+```
+
 # UC04
 ```ts
 import {SemanticModelAggregator} from "@dataspecer/core-v2/semantic-model/aggregator";

packages/core-v2/package.json

@@ -6,6 +6,7 @@
     "prebuild": "rimraf lib"
   },
   "exports": {
+    "./project": "./lib/src/project/index.js",
     "./semantic-model/aggregator": "./lib/src/semantic-model/aggregator/index.js",
     "./semantic-model/concepts": "./lib/src/semantic-model/concepts/index.js",
     "./semantic-model/simplified": "./lib/src/semantic-model/simplified/index.js",

packages/core-v2/src/project/index.ts

@@ -0,0 +1,3 @@
+export {BackendPackageService} from "./package/implementation";
+export {Package, PackageEditable} from "./package/package";
+export {PackageService, SemanticModelPackageService} from "./package/package-service";

packages/core-v2/src/project/package/implementation.ts

@@ -0,0 +1,74 @@
+import {PackageService, SemanticModelPackageService} from "./package-service";
+import {EntityModel} from "../../entity-model";
+import {Package, PackageEditable} from "./package";
+import {HttpFetch} from "@dataspecer/core/io/fetch/fetch-api";
+
+/**
+ * Implementation of PackageService that communicates with backend and provides semantic models.
+ */
+export class BackendPackageService implements PackageService, SemanticModelPackageService {
+    private readonly backendUrl: string;
+    protected readonly httpFetch: HttpFetch;
+
+    constructor(backendUrl: string, httpFetch: HttpFetch) {
+        this.backendUrl = backendUrl;
+        this.httpFetch = httpFetch;
+    }
+
+    async getPackage(packageId: string): Promise<Package> {
+        const result = await this.httpFetch(this.getPackageUrl(packageId).toString());
+        return await result.json() as Package;
+    }
+
+
+    async createPackage(parentPackageId: string, data: PackageEditable): Promise<Package> {
+        const result = await this.httpFetch(this.getPackageUrl(parentPackageId).toString(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(data),
+        });
+        return await result.json() as Package;
+    }
+
+    async updatePackage(packageId: string, data: Partial<PackageEditable>): Promise<Package> {
+        const result = await this.httpFetch(this.getPackageUrl(packageId).toString(), {
+            method: "PATCH",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(data),
+        });
+        return await result.json() as Package;
+    }
+
+    async deletePackage(packageId: string): Promise<void> {
+        await this.httpFetch(this.getPackageUrl(packageId).toString(), {
+            method: "DELETE",
+        });
+    }
+
+    async constructSemanticModelPackageModels(packageId: string): Promise<EntityModel[]> {
+        return [];
+    }
+
+    async updateSemanticModelPackageModels(packageId: string, models: EntityModel[]): Promise<Package> {
+        const url = this.getPackageUrl(packageId);
+        url.pathname += "/set-semantic-models";
+        const result = await this.httpFetch(this.getPackageUrl(packageId).toString(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(models),
+        });
+        return await result.json() as Package;
+    }
+
+    private getPackageUrl(packageId: string): URL {
+        const url = new URL(this.backendUrl + "/packages");
+        url.searchParams.append("packageId", packageId);
+        return url;
+    }
+}

packages/core-v2/src/project/package/package-service.ts

@@ -0,0 +1,41 @@
+import {EntityModel} from "../../entity-model";
+import {Package, PackageEditable} from "./package";
+
+/**
+ * Provides basic operations with packages.
+ */
+export interface PackageService {
+    /**
+     * Returns package with all sub-packages.
+     */
+    getPackage(packageId: string): Promise<Package>;
+
+    /**
+     * Create a new empty package that can be used to store other packages or models.
+     */
+    createPackage(parentPackageId: string, data: PackageEditable): Promise<Package>;
+
+    /**
+     * Updates editable package metadata.
+     */
+    updatePackage(packageId: string, data: Partial<PackageEditable>): Promise<Package>;
+
+    /**
+     * Removes the package with all models and sub-packages.
+     */
+    deletePackage(packageId: string): Promise<void>;
+}
+
+export interface SemanticModelPackageService extends PackageService {
+    /**
+     * Constructs all models from a package with semantic model.
+     */
+    constructSemanticModelPackageModels(packageId: string): Promise<EntityModel[]>;
+
+    /**
+     * Sets semantic models that should be stored in the given package.
+     * If the set of models is changed (new model is added or existing is removed), this method should be called.
+     * It will update the models that are stored in the package.
+     */
+    updateSemanticModelPackageModels(packageId: string, models: EntityModel[]): Promise<Package>;
+}

packages/core-v2/src/project/package/package.ts

@@ -0,0 +1,48 @@
+import {LanguageString} from "../../semantic-model/concepts";
+
+/**
+ * Package is de-facto a directory in the file system that contains other packages or models.
+ *
+ * Each package can have metadata (name, tags, authors), which are stored as a package metadata model, but are
+ * interpreted as a part of the package interface.
+ */
+export interface Package {
+    /**
+     * Path-like identifier of the package
+     */
+    id: string;
+
+    /**
+     * Name of the package which can be extracted either from the package-metadata or from the
+     * package identifier.
+     */
+    name: LanguageString;
+
+    /**
+     * Package tags that can be used for filtering, searching or organizing packages.
+     * Each tag is a case-insensitive string, that does not need to be registered in advance.
+     */
+    tags: string[];
+
+    /**
+     * Packages that are contained in this package
+     */
+    subPackages: Package[];
+
+    /**
+     * Whether this package can be interpreted as "data specification"-specification providing semantic model.
+     */
+    providesSemanticModel: boolean;
+}
+
+/**
+ * Package field that can be edited.
+ */
+export type PackageEditable = Omit<Package, "subPackages" | "providesSemanticModel">;
+
+/**
+ * Package that provides semantic model.
+ */
+interface SemanticModelPackage extends Package {
+
+}