@api-client/core 0.6.5 → 0.6.6

package/src/models/data/DataProperty.ts

@@ -0,0 +1,306 @@
+import { IThing, Thing } from "../Thing.js";
+import v4 from '../../lib/uuid.js';
+import { DataNamespace } from "./DataNamespace.js";
+import { IDataPropertySchema } from "./DataPropertySchema.js";
+
+export type DataPropertyType = 'string' | 'number' | 'nil' | 'boolean' | 'date' | 'datetime' |
+  'time' | 'bytes' | 'any' | 'file';
+export const DataPropertyTypes: DataPropertyType[] = [
+  'string', 'number', 'nil', 'boolean', 'date', 'datetime', 'time', 'bytes', 'any', 'file'
+];
+
+export enum DataPropertyList {
+  string = 'string',
+  number = 'number',
+  nil = 'nil',
+  boolean = 'boolean',
+  date = 'date',
+  datetime = 'datetime',
+  time = 'time',
+  bytes = 'bytes',
+  any = 'any',
+  file = 'file',
+}
+
+export const Kind = 'Core#DataProperty';
+
+export interface IPropertySchema<T> {
+  /**
+   * Whether it is a general schema for the property.
+   * All other schemas inherit from this one. This allows creating global schema description 
+   * like examples, default values, minimum value, etc and then use it as a base to generate specific formats.
+   * 
+   * A property may not have a global schema.
+   */
+  global?: boolean;
+  /**
+   * The mime type this schema describes.
+   * For JSON it is `application/json`, for XML it is `application/xml` (or `text/xml`) adn so on.
+   * 
+   * Note, when this value is missing then it is assumed that the schema is `global`.
+   */
+  format?: string;
+  /**
+   * The schema definition.
+   */
+  value: IDataPropertySchema<T>;
+}
+
+export interface IDataProperty {
+  kind: typeof Kind;
+  /**
+   * The key of the namespace.
+   */
+  key: string;
+  /**
+   * The data property description.
+   */
+  info: IThing;
+  /**
+   * Wether the data property is required.
+   */
+  required?: boolean;
+  /**
+   * Whether the data property allows multiple items.
+   */
+  multiple?: boolean;
+  /**
+   * Whether this property describes a primary key of the entity.
+   */
+  primary?: boolean;
+  /**
+   * Whether this property describes an indexed property of the entity.
+   */
+  index?: boolean;
+  /**
+   * Optional general purpose tags for the UI.
+   */
+  tags?: string[];
+  /**
+   * For future use.
+   * 
+   * The keys of the taxonomy items associated with the property.
+   */
+  taxonomy?: string[];
+  /**
+   * The data type for this property.
+   * Note, not all schemas support the same type. For example, defining `sint32` 
+   * works for protocol buffers but does not for JSON. In such case we use default 
+   * translation `sint32` -> `number`. Another way it to create 
+   * a derivative entity for specific schema to describe specific schema case.
+   */
+  type: DataPropertyType;
+
+  /**
+   * While the `DataProperty` describes the general shape of the data and can be used to 
+   * model the structure of the data in the system, a schema describes hwo the data 
+   * should be serialized into a specific format. This allows adding example values,
+   * default values, specifying data format, etc. The assumption here is
+   * that with enough specifics provided by the user (a domain specialist)
+   * we can automatically generate a schema for the given format.
+   */
+  schemas?: IPropertySchema<unknown>[];
+}
+
+export class DataProperty {
+  kind = Kind;
+
+  key = '';
+
+  /**
+   * The description of the data namespace.
+   */
+  info: Thing = Thing.fromName('');
+
+  /**
+   * Wether the data property is required.
+   */
+  required?: boolean;
+
+  /**
+   * Whether the data property allows multiple items.
+   */
+  multiple?: boolean;
+
+  /**
+   * Whether this property describes a primary key of the entity.
+   */
+  primary?: boolean;
+
+  /**
+   * Whether this property describes an indexed property of the entity.
+   */
+  index?: boolean;
+
+  /**
+   * Optional general purpose tags for the UI.
+   */
+  tags: string[] = [];
+
+  /**
+   * Reserved for future use.
+   * 
+   * The keys of the taxonomy items associated with the property.
+   */
+  taxonomy: string[] = [];
+
+  /**
+   * The data type for this property.
+   * Note, not all schemas support the same type. For example, defining `sint32` 
+   * works for protocol buffers but does not for JSON. In such case we use default 
+   * translation `sint32` -> `number`. Another way it to create 
+   * a derivative entity for specific schema to describe specific schema case.
+   */
+  type: DataPropertyType = 'string';
+
+  /**
+   * While the `DataProperty` describes the general shape of the data and can be used to 
+   * model the structure of the data in the system, a schema describes hwo the data 
+   * should be serialized into a specific format. This allows adding example values,
+   * default values, specifying data format, etc. The assumption here is
+   * that with enough specifics provided by the user (a domain specialist)
+   * we can automatically generate a schema for the given format.
+   */
+  schemas: IPropertySchema<unknown>[] = [];
+
+  static get supportedTypes(): DataPropertyType[] {
+    return [...DataPropertyTypes];
+  }
+
+  static fromName(root: DataNamespace, name: string): DataProperty {
+    const property = new DataProperty(root);
+    property.info = Thing.fromName(name);
+    return property;
+  }
+
+  static fromType(root: DataNamespace, type: DataPropertyType): DataProperty {
+    const assoc = new DataProperty(root);
+    assoc.type = type;
+    return assoc;
+  }
+
+  /**
+   * @param input The data property definition to restore.
+   */
+  constructor(protected root: DataNamespace, input?: string | IDataProperty) {
+    let init: IDataProperty;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        key: v4(),
+        info: Thing.fromName('').toJSON(),
+        type: 'string',
+      };
+    }
+    this.new(init);
+  }
+
+  new(init: IDataProperty): void {
+    if (!DataProperty.isDataProperty(init)) {
+      throw new Error(`Not a data property.`);
+    }
+    const { info, key = v4(), kind = Kind, multiple, required, type = DataPropertyList.string, index, primary, tags, taxonomy, schemas } = init;
+    this.kind = kind;
+    this.key = key;
+    this.type = type;
+    if (info) {
+      this.info = new Thing(info);
+    } else {
+      this.info = Thing.fromName('');
+    }
+    if (typeof multiple === 'boolean') {
+      this.multiple = multiple;
+    } else {
+      this.multiple = undefined;
+    }
+    if (typeof required === 'boolean') {
+      this.required = required;
+    } else {
+      this.required = undefined;
+    }
+    if (typeof index === 'boolean') {
+      this.index = index;
+    } else {
+      this.index = undefined;
+    }
+    if (typeof primary === 'boolean') {
+      this.primary = primary;
+    } else {
+      this.primary = undefined;
+    }
+    if (Array.isArray(tags)) {
+      this.tags = [...tags];
+    } else {
+      this.tags = [];
+    }
+    if (Array.isArray(taxonomy)) {
+      this.taxonomy = [...taxonomy];
+    } else {
+      this.taxonomy = [];
+    }
+    if (Array.isArray(schemas)) {
+      this.schemas = schemas.map(i => ({ ...i }));
+    } else {
+      this.schemas = [];
+    }
+  }
+
+  static isDataProperty(input: unknown): boolean {
+    const typed = input as IDataProperty;
+    if (!input || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IDataProperty {
+    const result: IDataProperty = {
+      kind: Kind,
+      info: this.info.toJSON(),
+      key: this.key,
+      type: this.type || DataPropertyList.string,
+    };
+    if (typeof this.index === 'boolean') {
+      result.index = this.index;
+    }
+    if (typeof this.primary === 'boolean') {
+      result.primary = this.primary;
+    }
+    if (typeof this.multiple === 'boolean') {
+      result.multiple = this.multiple;
+    }
+    if (typeof this.required === 'boolean') {
+      result.required = this.required;
+    }
+    if (Array.isArray(this.tags) && this.tags.length) {
+      result.tags = [...this.tags];
+    }
+    if (Array.isArray(this.taxonomy) && this.taxonomy.length) {
+      result.taxonomy = [...this.taxonomy];
+    }
+    if (Array.isArray(this.schemas) && this.schemas.length) {
+      result.schemas = this.schemas.map(i => ({ ...i }));
+    }
+    return result;
+  }
+
+  /**
+   * Removes self from the parent entity and the namespace definition.
+   */
+  remove(): void {
+    const { root } = this;
+    const entity = root.definitions.entities.find(i => i.properties.some(j => j === this));
+    if (entity) {
+      const assocIndex = entity.properties.findIndex(i => i === this);
+      entity.properties.splice(assocIndex, 1);
+    }
+    const defIndex = this.root.definitions.properties.findIndex(i => i.key === this.key);
+    if (defIndex >= 0) {
+      this.root.definitions.properties.splice(defIndex, 1);
+    }
+  }
+}

package/src/models/data/DataPropertySchema.ts

@@ -0,0 +1,156 @@
+export type NumberFormat = 'integer' | 'float' | 'long' | 'double' | 'int32' | 'int64' | 'uint32' | 'uint64' |
+  'sint32' | 'sint64' | 'fixed32' | 'fixed64' | 'sfixed32' | 'sfixed64';
+export const NumberFormats: NumberFormat[] = [
+  'integer', 'float', 'long', 'double', 'int32', 'int64', 'uint32', 'uint64', 'sint32', 'sint64', 'fixed32', 'fixed64',
+  'sfixed32', 'sfixed64'
+];
+
+export enum NumberFormatList {
+  integer = 'integer',
+  float = 'float',
+  int32 = 'int32',
+  int64 = 'int64',
+  uint32 = 'uint32',
+  uint64 = 'uint64',
+  sint32 = 'sint32',
+  sint64 = 'sint64',
+  fixed32 = 'fixed32',
+  fixed64 = 'fixed64',
+  sfixed32 = 'sfixed32',
+  sfixed64 = 'sfixed64',
+  double = 'double',
+}
+
+export type DateFormat = 'rfc3339' | 'rfc2616';
+export const DateFormats: DateFormat[] = ['rfc3339', 'rfc2616'];
+export enum DateFormatList {
+  /**
+   * The "date-time" notation of RFC3339
+   */
+  rfc3339 = 'rfc3339',
+  /**
+   * The format defined in RFC2616.
+   */
+  rfc2616 = 'rfc2616',
+}
+
+/**
+ * The difference between the DataProperty and this is that the `DataProperty` describes the general shape of 
+ * the data and `IDataPropertySchema` describes how this property is translated into a specific format
+ * (like JSON, Protocol Buffer, XML, etc)
+ */
+export interface IDataPropertySchema<T> {
+  // Common
+
+  /**
+   * The default value for the property.
+   */
+  default?: T;
+
+  /**
+   * Enum values for the property.
+   */
+  enum?: T[];
+
+  /**
+   * The example value for the property.
+   */
+  examples?: T[];
+
+  /**
+   * The format of a `number` or `datetime` type.
+   */
+  format?: NumberFormat | DateFormat;
+
+  /**
+   * Minimum length of the string or a file. Value MUST be equal to or greater than 0.
+   */
+  minLength?: number;
+  
+  /**
+   * The minimum length of the string or a file. Value MUST be equal to or greater than 0.
+   */
+  maxLength?: number;
+
+
+  // STRING
+
+  /**
+   * Regular expression that this string MUST match.
+   */
+  pattern?: string;
+
+  // NUMBER
+
+  /**
+   * The minimum value.
+   */
+  minimum?: number;
+
+  /**
+   * The maximum value.
+   */
+  maximum?: number;
+
+  /**
+   * A numeric instance is valid against "multipleOf" if the result of dividing the instance by this 
+   * value is an integer.
+   */
+  multipleOf?: number;
+
+  // File
+
+  /**
+   * A list of valid content-type strings for the file. The file type `*\/*` is a valid value.
+   */
+  fileTypes?: string[];
+
+  // XML serialization
+
+  /**
+   * Describes XML specific serialization.
+   */
+  xml?: {
+    /**
+     * Whether is property should be represented as an attribute of the parent entity.
+     * 
+     * ```
+     * <Person name="John Doe"></Person>
+     * ```
+     */
+    attribute?: boolean;
+
+    /**
+     * The name of the attribute or a wrapped property to use when serializing the property.
+     * 
+     * ```
+     * <Person fullName="John Doe"></Person>
+     * ```
+     */
+    name?: string;
+
+    /**
+     * When the property is an array (has the `multiple` set to true)
+     * then it tells that the list of values should be wrapped with a parent
+     * element:
+     * 
+     * ```
+     * <Person>
+     *  <Person fullName="John Doe"></Person>
+     * </Person>
+     * ```
+     * 
+     * Use this with the combination with `name` to describe the name of the wrapped
+     * element
+     * 
+     * ```
+     * <people>
+     *  <Person fullName="John Doe"></Person>
+     * </people>
+     * ```
+     * 
+     * Note, this is mutually exclusive with `attribute`.
+     */
+    wrapped?: boolean;
+  }
+}

package/src/runtime/store/FilesSdk.ts

@@ -6,6 +6,7 @@ import { IUser } from '../../models/store/User.js';
 import { IFile } from '../../models/store/File.js';
 import { Kind as ProjectKind } from '../../models/Project.js';
 import { Kind as WorkspaceKind } from '../../models/Workspace.js';
+import { Kind as DataNamespaceKind } from '../../models/data/DataNamespace.js';
 import { IHttpProject } from '../../models/HttpProject.js';
 import { SdkError } from './Errors.js';
 
@@ -17,15 +18,17 @@ export interface IFileCreateOptions {
   parent?: string;
 }
 
+export type FileKind = typeof ProjectKind | typeof WorkspaceKind | typeof DataNamespaceKind;
+
 export class FilesSdk extends SdkBase {
   /**
    * Lists files (spaces, projects, etc) in the store.
    * 
-   * @param kinds the list of kinds to list. Spaces are always included.
+   * @param kinds Optional list of kinds to limit the file types in the result. Spaces are always included.
    * @param options Optional query options.
    * @param request Optional request options.
    */
-  async list(kinds: (typeof ProjectKind | typeof WorkspaceKind)[], options?: IListOptions, request: ISdkRequestOptions = {}): Promise<IListResponse<IFile>> {
+  async list(kinds: FileKind[], options?: IListOptions, request: ISdkRequestOptions = {}): Promise<IListResponse<IFile>> {
     const token = request.token || this.sdk.token;
     const url = this.sdk.getUrl(RouteBuilder.files());
     this.sdk.appendListOptions(url, options);