Improve docs

Author: lorefnon

src/ArgMapping.ts

@@ -72,7 +72,7 @@ export interface ArgMapping<TMapped extends t.Type<any>> extends t.TypeOf<typeof
      *
      * This opens up the ability to map an argument value to an arbitrary database query operation.
      */
-    interceptQuery?: (qb: Knex.QueryBuilder, value: t.TypeOf<TMapped>, args: Dict) => Knex.QueryBuilder;
+    interceptQuery?: (queryBuilder: Knex.QueryBuilder, value: t.TypeOf<TMapped>, args: Dict) => Knex.QueryBuilder;
     /**
      * Can be used to intercept the derived entity to be used for the operation this argument is part of.
      *

src/AssociationMapping.ts

@@ -206,6 +206,11 @@ export const AssociationMappingRT = t.intersection([
 ]);
 
 /**
+ * Configuration used to map an association.
+ *
+ * Association mapping determines how two data sources can be linked (through joins, or auxiliary queries) so
+ * that operations can be performed over multiple data sources.
+ *
  * @api-category ConfigType
  */
 export interface AssociationMapping<TSrc extends MappedDataSource = any, TTgt extends MappedDataSource = any>

src/DataSourceMapping.ts

@@ -9,16 +9,42 @@ import { MappedAssociation } from "./MappedAssociation";
 export const DataSourceMappingRT = t.intersection([
     t.type({
         /**
-         * Name of data source
+         * Name of the data source.
          *
-         * This can either be a string or an object with stored and mapped properties
+         * This can either be a string or an object with stored and mapped properties.
+         *
+         * If provided as a string, then the mapped name of the data source
+         * will be PascalCased singular variant of the name, and the stored name
+         * will be the snake_cased pluralized variant.
+         *
+         * Eg. if name is specified either as "ProductManager" or "product_managers",
+         * in both cases they will be normalized as:
+         *
+         * ```
+         * {
+         *     stored: 'product_managers',
+         *     mapped: 'ProductManager'
+         * }
+         * ```
+         *
+         * Unless rootQuery is specified, the stored name will be used to identify the table to connect to.
+         *
+         * If exposed, the GraphQL type names are derived from the mapped name:
+         *
+         * - `ProductManager` - primary GraphQL output type for the entity
+         * - `ShallowProductManager` - GraphQL output type containing only the fields and not associations
+         * - `ProductManagerInput` - GraphQL input type for the entity
+         * - `ShallowProductManagerInput` - Graphql input type for shallow entity (excludes associations)
          *
          * @property
          * @memberof DataSourceMapping
          */
         name: MaybeMapped(t.string, t.string),
     }),
     t.partial({
+        /**
+         * Human friendly description of an entity from this data source.
+         */
         description: t.string,
         fields: t.Function,
         associations: t.Function,
@@ -28,20 +54,47 @@ export const DataSourceMappingRT = t.intersection([
 ]);
 
 /**
- * Configuration for mapping a data source.
+ * Make sure you have gone through the [DataSource Mapping](guide:mapping-data-sources) guide first, which provides a high level overview of how data mapping works in practice
+ * in GRelDAL.
+ *
+ * A DataSource mapping facilitates the mapping between the persistence layer and the application level entities.
  *
- * Make sure you have seen the Data Mapping Guide
+ * It has following major responsibilities:
+ *
+ * 1. To specify how the data source connects to the persistence layer.
+ * 2. To describe the shape of a `row` stored in the persistence layer
+ * 3. To describe the shape of an `entity` exposed to the application layer.
+ * 4. To define the mapping between the two representations so an entity can be coverted to a row and vice versa.
+ * 5. To define how this data source can connect to other data sources through joins or side-loading
  *
  * @api-category ConfigType
  */
-export type DataSourceMapping = t.TypeOf<typeof DataSourceMappingRT> & {
+export interface DataSourceMapping extends t.TypeOf<typeof DataSourceMappingRT> {
     /**
-     * Mapping of fieldNames to Configuration for fields
-     *
-     * Refer [FieldMapping](api:FieldMapping) for specifics
+     * Field mapping obtained from [mapFields](api:mapFields)
      */
     fields?: (dataSource: MappedDataSource) => Dict<MappedField>;
+
+    /**
+     * Association mapping obtained from [mapAssociations](api:mapAssociations)
+     */
     associations?: (dataSource: MappedDataSource) => Dict<MappedAssociation>;
+
+    /**
+     * By default dataSources will connect to a table matching storedName.
+     *
+     * Using a rootQuery we can configure the data source to connect to a different table, or a join of multiple tables.
+     * Note that when working with joins, it is generally recommended to use associations over mapping to joined tables.
+     */
     rootQuery?: (alias: Maybe<AliasHierarchyVisitor>) => Knex.QueryBuilder;
+
+    /**
+     * Dedicated Knex instance to be used for this data source.
+     *
+     * If not provided, the knex instance globally configured through [useDatabaseConnector](api:useDatabaseConnector) will be used.
+     *
+     * DataSource specific connector is primarily useful for supporting polyglot persistence and enables use of different
+     * databases within the application.
+     */
     connector?: Knex;
-};
+}

src/MappedAssociation.ts

@@ -41,6 +41,9 @@ export class MappedAssociation<TSrc extends MappedDataSource = any, TTgt extends
         );
     }
 
+    /**
+     * If the association will resolve to at most one associated entity
+     */
     @MemoizeGetter
     get singular() {
         if (isBoolean(this.mapping.singular)) {
@@ -49,22 +52,38 @@ export class MappedAssociation<TSrc extends MappedDataSource = any, TTgt extends
         return singularize(this.mappedName) === this.mappedName;
     }
 
+    /**
+     * If the association will be exposed through GraphQL API
+     */
     get exposed() {
         return this.mapping.exposed !== false;
     }
 
+    /**
+     * Linked data source
+     */
     get target(): TTgt {
         return this.mapping.target.apply(this);
     }
 
+    /**
+     * Association description made available through the GraphQL API
+     */
     get description() {
         return this.mapping.description;
     }
 
+    /**
+     * If the association supports paginated response
+     */
     get isPaginated() {
         return !!this.mapping.paginate;
     }
 
+    /**
+     * For a given operation, identify one of the (potentially) many many fetch configurations specified
+     * using the fetchThrough mapping property.
+     */
     getFetchConfig<
         TCtx extends ResolverContext<TMappedOperation, TRootSrc, TGQLArgs, TGQLSource, TGQLContext>,
         TRootSrc extends MappedDataSource<any>,
@@ -186,27 +205,68 @@ export class MappedAssociation<TSrc extends MappedDataSource = any, TTgt extends
         };
     }
 
+    /**
+     * Columns used to link the data sources at the persistence layer
+     */
     get associatorColumns() {
         return this.mapping.associatorColumns;
     }
 
+    /**
+     * Getter to obtain the type of source DataSource.
+     *
+     * This is expected to be used only in mapped typescript types. Invoking the getter directly
+     * at runtime will throw.
+     */
     get DataSourceType(): TSrc {
         throw getTypeAccessorError("DataSourceType", "MappedAssociation");
     }
 
+    /**
+     * Getter to obtain the type of associated DataSource.
+     *
+     * This is expected to be used only in mapped typescript types. Invoking the getter directly
+     * at runtime will throw.
+     */
     get AssociatedDataSourceType(): TTgt {
         throw getTypeAccessorError("AssociatedDataSourceType", "MappedAssociation");
     }
 
+    /**
+     * Getter to obtain the type of entity from source DataSource.
+     *
+     * This is expected to be used only in mapped typescript types. Invoking the getter directly
+     * at runtime will throw.
+     */
     get SourceEntityType(): TSrc["EntityType"] {
         throw getTypeAccessorError("SourceEntityType", "MappedAssociation");
     }
 
+    /**
+     * Getter to obtain the type of entity from associated DataSource.
+     *
+     * This is expected to be used only in mapped typescript types. Invoking the getter directly
+     * at runtime will throw.
+     */
     get AssociatedEntityType(): TTgt["EntityType"] {
         throw getTypeAccessorError("AssociatedEntityType", "MappedAssociation");
     }
 }
 
+/**
+ * Used to define an association between two data sources.
+ *
+ * Make sure you have gone through the [Association Mapping](guide:mapping-associations) guide first which elaborates on
+ * the concepts behind association mapping.
+ *
+ * Association mapping determines how two data sources can be linked (through joins, or auxiliary queries) so
+ * that operations can be performed over multiple data sources.
+ *
+ * Accepts an [AssociationMapping](api:AssociationMapping) configuration.
+ *
+ * @api-category PrimaryAPI
+ * @param associations
+ */
 export const mapAssociations = <TMapping extends Dict<AssociationMapping<any, MappedDataSource>>>(
     associations: TMapping,
 ) => <TSrc extends MappedDataSource>(

src/MappedDataSource.ts

@@ -34,9 +34,7 @@ type FieldKeysIn<T extends DataSourceMapping> = keyof FieldsIn<T>;
 
 type AssociatedDataSource<T extends DataSourceMapping, K extends AssociationKeysIn<T>> = AssociationsIn<T>[K]["target"];
 
-type ShallowEntityType<T extends DataSourceMapping> = {
-    [K in FieldKeysIn<T>]: t.TypeOf<FieldsIn<T>[K]["type"]>
-};
+type ShallowEntityType<T extends DataSourceMapping> = { [K in FieldKeysIn<T>]: t.TypeOf<FieldsIn<T>[K]["type"]> };
 
 type NestedEntityType<T extends DataSourceMapping> = ShallowEntityType<T> &
     { [K in AssociationKeysIn<T>]: AssociatedDataSource<T, K>["EntityType"] };

src/MappedField.ts

@@ -257,6 +257,9 @@ export class MappedField<
     }
 }
 
+/**
+ * @api-category PrimaryAPI
+ */
 export const mapFields = <TFieldMapping extends Dict<FieldMapping<t.Type<any>, TArgs>>, TArgs extends {}>(
     fields: TFieldMapping,
 ) => <TSrc extends MappedDataSource>(

src/connector.ts

@@ -51,6 +51,8 @@ export const assertConnectorConfigured = (connector?: Maybe<Knex>) => {
  * Register a database connector as the global default for the library.
  *
  * Connector options can be found in [knex documentation](https://knexjs.org/#Installation-client).
+ *
+ * @api-category PrimaryAPI
  */
 export const useDatabaseConnector = (connector: Knex) => {
     globalConnector = assertSupportedConnector(connector);

src/docs/components/APIBody.js

@@ -1,5 +1,6 @@
-import APIEntityContainer from "./APIEntityContainer";
+import APIEntityContainer, {APIContainer} from "./APIEntityContainer";
 import styled from "styled-components";
+import { Link } from "./Link";
 
 export const EmptyMsgContainer = styled.div`
     color: silver;
@@ -11,9 +12,101 @@ export const EmptyMsgContainer = styled.div`
     line-height: 4rem;
 `;
 
+export function APIIntro(props) {
+    return (
+        <APIContainer>
+            <h1>Welcome to GRelDAL's API Documentation </h1>
+            <div>
+                Please make sure that you have first gone through the <Link href="guides">Guides</Link> before diving
+                deep into the API docs.
+            </div>
+            <div>
+                <h1>Terms</h1>
+                <p>Summary of the terminology used in the API docs</p>
+                <ul>
+                    <li>
+                        <strong>DataSource</strong>
+                        <p>
+                            A DataSource is a mapper that mediates operations against a table/view in the persistence
+                            layer.
+                        </p>
+                        <p>
+                            DataSources are expected to have a fixed set of <strong>fields</strong> (see below) and can
+                            interact with other data sources through <strong>associations</strong> (see below).
+                        </p>
+                    </li>
+                    <li>
+                        <strong>Entity</strong>
+                        <p>
+                            Entities are plain JavaScript objects returned by operations on data sources.
+                        </p>
+                        <p>
+                            When application logic is written against Entities, it is sheilded from the specifics 
+                            of persistence layer. Using plain js entities instead of ORM models or managed instances
+                            prevents accidental coupling of application logic and persistence specific concerns.
+                        </p>
+                        <p>
+                            The shape of an entity may not be same as rows in the underlying persistence layer (table or
+                            view) and whenever required, the DataSource will perform coversion between rows and
+                            entities.
+                        </p>
+                    </li>
+                    <li>
+                        <strong>Row</strong>
+                        <p>
+                            In the documentation here, rows always refer to rows in a table/view in the persistence
+                            layer.
+                        </p>
+                    </li>
+                    <li>
+                        <strong>Association</strong>
+                        <p>An association is a link using which operations can span over multiple data source</p>
+                    </li>
+                    <li>
+                        <strong>Field</strong>
+                        <p>
+                            A field refers to an attribute in an Entity. A field can either be directly mapped from a
+                            column or be derived from a combination of multiple columns.
+                        </p>
+                        <p>
+                            The <Link href="mapping-data-sources">DataSource mapping guide</Link> elaborates more on
+                            mapping fields.
+                        </p>
+                    </li>
+                </ul>
+            </div>
+            <div>
+                <h1>Important top level functions</h1>
+                <ul>
+                    <li>
+                        <strong>useDatabaseConnector</strong>
+                        <p>
+                            Configures a knex instance to be used for connecting to the database. For polyglot
+                            persistence, we can also specify a knex instance at a data source level.
+                        </p>
+                    </li>
+                    <li>
+                        <strong>mapDataSource</strong>
+                        <p>
+                            Map tables (or views) in database to data sources which operations exposed through the
+                            GraphQL schema can interact with.
+                        </p>
+                    </li>
+                    <li>
+                        <strong>mapSchema</strong>
+                        <p>Derive a GraphQL schema from GRelDAL data sources and operations.</p>
+                    </li>
+                </ul>
+            </div>
+            <h2>Looking for a particular class/function ?</h2>
+            <p>← Find it through the sidebar</p>
+        </APIContainer>
+    );
+}
+
 export default function APIBody(props) {
     if (!props.activeCategory || !props.rootEntity) {
-        return <EmptyMsgContainer>Select an entity from sidebar</EmptyMsgContainer>;
+        return <APIIntro />;
     }
     return <APIEntityContainer entity={props.rootEntity} activeEntityName={props.activeEntityName} />;
 }