stash initial changes

packages/experimental-preview-types/src/cache/aliases.ts

@@ -0,0 +1,12 @@
+// The ResourceBlob is an opaque type that must
+// satisfy two constraints.
+// (1) it should be possible for the IdentifierCache
+// to be able to generate a RecordIdentifier for it
+// whether by default or due to configuration.
+// (2) it should be in a format expected by the Cache.
+// This format is Cache declared.
+//
+// this Opaqueness allows arbitrary storage of any
+// serializable / transferable state including such things
+// as Buffers and Strings.
+export type ResourceBlob = unknown;

packages/experimental-preview-types/src/cache/change.ts

@@ -0,0 +1,9 @@
+import { StableRecordIdentifier } from '@ember-data/types/q/identifier';
+
+import { StableDocumentIdentifier } from './identifier';
+
+export interface Change {
+  identifier: StableRecordIdentifier | StableDocumentIdentifier;
+  op: 'upsert' | 'remove';
+  patch?: unknown;
+}

packages/experimental-preview-types/src/cache/document.ts

@@ -0,0 +1,43 @@
+import type { ImmutableRequestInfo, ResponseInfo as ImmutableResponseInfo } from '@ember-data/request/-private/types';
+import { Links, Meta, PaginationLinks } from '@ember-data/types/q/ember-data-json-api';
+import { StableRecordIdentifier } from '@ember-data/types/q/identifier';
+
+export type RequestInfo = ImmutableRequestInfo;
+export type ResponseInfo = ImmutableResponseInfo;
+
+export interface ResourceMetaDocument {
+  // the url or cache-key associated with the structured document
+  lid: string;
+  meta: Meta;
+  links?: Links | PaginationLinks;
+}
+
+export interface ResourceDataDocument {
+  // the url or cache-key associated with the structured document
+  lid: string;
+  links?: Links | PaginationLinks;
+  meta?: Meta;
+  data: StableRecordIdentifier | StableRecordIdentifier[] | null;
+}
+
+export interface ResourceErrorDocument {
+  // the url or cache-key associated with the structured document
+  lid: string;
+  links?: Links | PaginationLinks;
+  meta?: Meta;
+  error: string | object;
+}
+
+export type ResourceDocument = ResourceMetaDocument | ResourceDataDocument | ResourceErrorDocument;
+
+export interface StructuredDataDocument<T> {
+  request: RequestInfo;
+  response: ResponseInfo;
+  data: T;
+}
+export interface StructuredErrorDocument extends Error {
+  request: RequestInfo;
+  response: ResponseInfo;
+  error: string | object;
+}
+export type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;

packages/experimental-preview-types/src/cache/identifier.ts

@@ -0,0 +1,3 @@
+export type StableDocumentIdentifier = {
+  lid: string;
+};

packages/experimental-preview-types/src/cache/mutations.ts

@@ -0,0 +1,72 @@
+import { StableRecordIdentifier } from '@ember-data/types/q/identifier';
+
+export interface AddToRelatedRecordsMutation {
+  op: 'addToRelatedRecords';
+  record: StableRecordIdentifier;
+  field: string;
+  value: StableRecordIdentifier | StableRecordIdentifier[];
+  index?: number;
+}
+
+export interface RemoveFromRelatedRecordsMutation {
+  op: 'removeFromRelatedRecords';
+  record: StableRecordIdentifier;
+  field: string;
+  value: StableRecordIdentifier | StableRecordIdentifier[];
+  index?: number;
+}
+
+export interface ReplaceRelatedRecordMutation {
+  op: 'replaceRelatedRecord';
+  record: StableRecordIdentifier;
+  field: string;
+  // never null if field is a collection
+  value: StableRecordIdentifier | null;
+  // if field is a collection,
+  //  the value we are swapping with
+  prior?: StableRecordIdentifier;
+  index?: number;
+}
+
+export interface ReplaceRelatedRecordsMutation {
+  op: 'replaceRelatedRecords';
+  record: StableRecordIdentifier;
+  field: string;
+  // the records to add. If no prior/index
+  //  specified all existing should be removed
+  value: StableRecordIdentifier[];
+  // if this is a "splice" the
+  //  records we expect to be removed
+  prior?: StableRecordIdentifier[];
+  // if this is a "splice" the
+  //   index to start from
+  index?: number;
+}
+
+export interface SortRelatedRecordsMutation {
+  op: 'sortRelatedRecords';
+  record: StableRecordIdentifier;
+  field: string;
+  value: StableRecordIdentifier[];
+}
+// A Mutation is an action that updates
+// the local state of the Cache in some
+// manner.
+// Most Mutations are in theory also
+// Operations; with the difference being
+// that the change should be applied as
+// "local" or "dirty" state instead of
+// as "remote" or "clean" state.
+//
+// Note: this RFC does not publicly surface
+// any of the mutations listed here as
+// "operations", though the (private) Graph
+// already expects and utilizes these.
+// and we look forward to an RFC that makes
+// the Graph a fully public API.
+export type Mutation =
+  | ReplaceRelatedRecordsMutation
+  | ReplaceRelatedRecordMutation
+  | RemoveFromRelatedRecordsMutation
+  | AddToRelatedRecordsMutation
+  | SortRelatedRecordsMutation;

packages/experimental-preview-types/src/cache/operations.ts

@@ -0,0 +1,32 @@
+import { StableRecordIdentifier } from '@ember-data/types/q/identifier';
+
+export interface Op {
+  op: string;
+}
+
+// Occasionally the IdentifierCache
+// discovers that two previously thought
+// to be distinct Identifiers refer to
+// the same ResourceBlob. This Operation
+// will be performed giving the Cache the
+// change to cleanup and merge internal
+// state as desired when this discovery
+// is made.
+export interface MergeOperation extends Op {
+  op: 'mergeIdentifiers';
+  // existing
+  record: StableRecordIdentifier;
+  // new
+  value: StableRecordIdentifier;
+}
+
+export interface RemoveOperation extends Op {
+  op: 'removeIdentifier';
+  record: StableRecordIdentifier;
+}
+
+// An Operation is an action that updates
+// the remote state of the Cache in some
+// manner. Additional Operations will be
+// added in the future.
+export type Operation = MergeOperation | RemoveOperation;

packages/experimental-preview-types/src/cache/relationship.ts

@@ -0,0 +1,22 @@
+// Note: in v1 data could be a ResourceIdentifier, now
+import type { Value as JSONValue } from 'json-typescript';
+
+import { Links, PaginationLinks } from '@ember-data/types/q/ember-data-json-api';
+import { StableRecordIdentifier } from '@ember-data/types/q/identifier';
+
+// we request that it be in the stable form already.
+export interface ResourceRelationship {
+  data?: StableRecordIdentifier | null;
+  meta?: Record<string, JSONValue>;
+  links?: Links;
+}
+
+// Note: in v1 data could be a ResourceIdentifier, now
+// we request that it be in the stable form already.
+export interface CollectionRelationship {
+  data?: StableRecordIdentifier[];
+  meta?: Record<string, JSONValue>;
+  links?: PaginationLinks;
+}
+
+export type Relationship = ResourceRelationship | CollectionRelationship;

packages/experimental-preview-types/src/cache/validation-error.ts

@@ -0,0 +1,21 @@
+// An error relating to a Resource
+// Received when attempting to persist
+// changes to that resource.
+//
+// considered "opaque" to the Store itself.
+//
+// Currently we restrict Errors to being
+// shaped in JSON:API format; however,
+// this is a restriction we will willingly
+// recede if desired. So long as the
+// presentation layer and the cache and the
+// network layer are in agreement about the
+// schema of these Errors, then EmberData
+// has no reason to enforce this shape.
+export interface ValidationError {
+  title: string;
+  detail: string;
+  source: {
+    pointer: string;
+  };
+}