angular-odata 0.160.0 → 0.162.0

package/README.md

@@ -1,16 +1,18 @@
 <h1 align="center">Angular OData</h1>
 
 <p align="center">
-  <em>A fluent API for querying, creating, updating and deleting OData resources in Angular.</em>
+  <em>A typed, fluent client for OData services in Angular.</em>
   <br>
 </p>
 
 <p align="center">
-  <a href="CONTRIBUTING.md">Contributing</a>
+  <a href="https://diegomvh.github.io/angular-odata/docs/api/additional-documentation/introduction.html">Handbook</a>
   ·
-  <a href="./docs/api/index.html">Documentation</a>
+  <a href="https://diegomvh.github.io/angular-odata/docs/api/index.html">API reference</a>
   ·
   <a href="https://github.com/diegomvh/AngularODataEntity">Demo</a>
+  ·
+  <a href="https://github.com/diegomvh/angular-odata/blob/main/CONTRIBUTING.md">Contributing</a>
   <br>
   <br>
 </p>
@@ -26,14 +28,170 @@
 
 <hr>
 
-## Installation
+[OData](https://www.odata.org/) is a standard for REST APIs: every service describes its
+data in a `$metadata` document and accepts the same query options (`$filter`, `$select`,
+`$expand`, `$orderby`, …). **angular-odata** lets your Angular application talk to any OData
+service without writing URLs by hand: you build requests with typed TypeScript code and get
+back typed results.
+
+```typescript
+// GET People?$select=UserName,FirstName&$filter=contains(UserName, 'russell')&$top=10
+client
+  .entitySet<Person>('People')
+  .query((q) => {
+    q.filter(({ e, t }) => e().contains(t.UserName, 'russell'));
+    q.select(['UserName', 'FirstName']);
+    q.top(10);
+  })
+  .fetch()
+  .subscribe(({ entities }) => console.log(entities));
+```
+
+## Features
+
+- **Typed query builder**: `$filter`, `$select`, `$expand`, `$orderby`, `$search`,
+  `$compute`, `$apply` and paging, with field names checked by the compiler.
+- **Complete OData API**: entity sets, entities, navigation properties, functions,
+  actions, singletons, media and `$batch` requests.
+- **Code generation**: one command creates interfaces, services and models from your
+  service's `$metadata`.
+- **Models and collections**: change tracking, validation and `save()` / `destroy()`.
+- **Caching**: in-memory, Web Storage or IndexedDB, with fetch policies such as
+  `cache-first` and `cache-and-network`.
+- **Several APIs** in the same application, each with its own configuration.
 
-Install from npm:
+## Quick start
+
+### 1. Install
 
 ```bash
 npm i angular-odata
 ```
 
-## OData Version
+### 2. Register the client
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideODataClient } from 'angular-odata';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideODataClient({
+      config: { serviceRootUrl: 'https://services.odata.org/V4/TripPinServiceRW/' },
+    }),
+  ],
+};
+```
+
+Applications that use NgModules can import `ODataModule.forRoot({ config })` instead.
+
+### 3. Query your service
+
+```typescript
+import { Component, inject, signal } from '@angular/core';
+import { ODataClient } from 'angular-odata';
+
+interface Person {
+  UserName: string;
+  FirstName: string;
+  LastName: string;
+}
+
+@Component({
+  selector: 'app-people',
+  template: `
+    @for (person of people(); track person.UserName) {
+      <p>{{ person.FirstName }} {{ person.LastName }}</p>
+    }
+  `,
+})
+export class PeopleComponent {
+  private client = inject(ODataClient);
+  people = signal<Person[]>([]);
+
+  ngOnInit() {
+    this.client
+      .entitySet<Person>('People')
+      .query((q) => {
+        q.orderBy('LastName');
+        q.top(10);
+      })
+      .fetch()
+      .subscribe(({ entities }) => this.people.set(entities ?? []));
+  }
+}
+```
+
+### 4. Optional: generate a typed API
+
+Instead of writing interfaces and services by hand, generate them from the `$metadata` of
+your service:
+
+```bash
+ng generate angular-odata:apigen --name=TripPin --metadata='https://services.odata.org/V4/TripPinServiceRW/$metadata'
+```
+
+```typescript
+import { PeopleService, TripPinConfig } from './trip-pin';
+
+// app.config.ts
+provideODataClient({ config: TripPinConfig });
+
+// Any component or service
+const people = inject(PeopleService);
+people
+  .entity('russellwhyte')
+  .fetch()
+  .subscribe(({ entity }) => console.log(entity));
+```
+
+## A few more examples
+
+```typescript
+const people = client.entitySet<Person>('People');
+
+// Create, update and delete
+people.create({ UserName: 'jdoe', FirstName: 'John', LastName: 'Doe' }).subscribe();
+people.entity('jdoe').modify({ FirstName: 'Johnny' }).subscribe();
+people.entity('jdoe').destroy().subscribe();
+
+// Expand related entities: $expand=Trips($select=Name,Budget)
+people
+  .entity('russellwhyte')
+  .query((q) =>
+    q.expand(({ e, t }) =>
+      e().field(t.Trips, (f) => f.select(({ e, t }) => e().field(t.Name).field(t.Budget))),
+    ),
+  )
+  .fetch()
+  .subscribe(({ entity }) => console.log(entity?.Trips));
+
+// Follow the server's next links and get every entity
+people.fetchAll().subscribe(({ entities }) => console.log(entities.length));
+```
+
+## Documentation
+
+- **[Handbook](https://diegomvh.github.io/angular-odata/docs/api/additional-documentation/introduction.html)**:
+  guides for configuration, resources, the query builder, services, models, caching and code
+  generation.
+- **[API reference](https://diegomvh.github.io/angular-odata/docs/api/index.html)**: every
+  class and method, generated from the source code.
+- **[Demo application](https://github.com/diegomvh/AngularODataEntity)**: a complete Angular
+  application that uses the TripPin and Northwind sample services.
+
+## Compatibility
+
+- **Angular**: 20 or later.
+- **OData**: version 4 is fully supported; versions 3 and 2 have basic support.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Read the
+[contributing guide](https://github.com/diegomvh/angular-odata/blob/main/CONTRIBUTING.md)
+to get started.
+
+## License
 
-The library works mainly with OData Version 4, however, it incorporates basic support for versions 3 and 2.
+[MIT](https://github.com/diegomvh/angular-odata/blob/main/LICENSE)

package/fesm2022/angular-odata.mjs

@@ -1593,7 +1593,7 @@ const Objects = {
     },
     resolveKey(key, { single = true } = {}) {
         const type = Types.rawType(key);
-        if (['number', 'string'].indexOf(type) !== -1)
+        if (['Number', 'String'].indexOf(type) !== -1)
             return key;
         if (type !== 'Map' && type !== 'Object') {
             return undefined;
@@ -2153,9 +2153,9 @@ class ODataEnumTypeParser extends ODataAnnotatable {
         }
         return schema;
     }
-    validate(value, { method, navigation = false, } = {}) {
+    validate(value, { method, navigation = false, }) {
         if (this.flags) {
-            let fields = this.fields(value);
+            const fields = this.fields(value);
             return value && fields.length === 0 ? ['mismatch'] : undefined;
         }
         else {
@@ -2195,6 +2195,7 @@ class ODataStructuredTypeFieldParser extends ODataAnnotatable {
     navigation;
     nullable;
     default;
+    optimisticConcurrency = false;
     maxLength;
     precision;
     scale;
@@ -2215,7 +2216,7 @@ class ODataStructuredTypeFieldParser extends ODataAnnotatable {
         this.precision = field.precision;
         this.scale = field.scale;
     }
-    validate(value, { method, navigation = false, } = {}) {
+    validate(value, { method, navigation = false, }) {
         let errors;
         if (this.collection && Array.isArray(value)) {
             errors = value.map((v) => this.validate(v, { method, navigation }));
@@ -2231,12 +2232,8 @@ class ODataStructuredTypeFieldParser extends ODataAnnotatable {
         }
         else {
             // IsEdmType
-            const computed = this.annotatedValue(COMPUTED);
             errors = [];
-            if (!this.nullable &&
-                (value === null || (value === undefined && method !== 'modify')) && // Is null or undefined without patch?
-                !(computed && method === 'create') // Not (Is Computed field and create) ?
-            ) {
+            if (method !== 'modify' && value == null && !(this.nullable || this.isComputed())) {
                 errors.push(`required`);
             }
             if (this.maxLength !== undefined &&
@@ -2304,12 +2301,13 @@ class ODataStructuredTypeFieldParser extends ODataAnnotatable {
         });
     }
     //#endregion
-    configure({ options, parserForType, }) {
+    configure({ options, optimisticConcurrency, parserForType, }) {
         this.parserOptions = options;
         this.parser = parserForType(this.type);
-        if (this.default !== undefined) {
+        if (optimisticConcurrency !== undefined)
+            this.optimisticConcurrency = optimisticConcurrency;
+        if (this.default !== undefined)
             this.default = this.deserialize(this.default, options);
-        }
     }
     //#region Json Schema
     // https://json-schema.org/
@@ -2386,6 +2384,12 @@ class ODataStructuredTypeFieldParser extends ODataAnnotatable {
     isKey() {
         return this.structured.keys({ include_parents: true }).some((k) => k.name === this.name);
     }
+    isComputed() {
+        return this.annotatedValue(COMPUTED);
+    }
+    isOptimisticConcurrency() {
+        return this.optimisticConcurrency;
+    }
     hasReferentials() {
         return this.referentials.length !== 0;
     }
@@ -2518,14 +2522,18 @@ class ODataStructuredTypeParser extends ODataAnnotatable {
         const parserOptions = { ...this.parserOptions, ...options };
         return raw(JSON.stringify(this.serialize(value, parserOptions)));
     }
-    configure({ options, parserForType, }) {
+    configure({ options, entitySet, parserForType, }) {
         this.parserOptions = options;
         if (this.base !== undefined) {
             this.parent = parserForType(this.base);
             if (this.parent !== undefined)
                 this.parent.children.push(this);
         }
-        this._fields.forEach((f) => f.configure({ options, parserForType }));
+        const optimisticConcurrencyFields = entitySet?.annotatedValue(OPTIMISTIC_CONCURRENCY) ?? [];
+        this._fields.forEach((field) => {
+            const optimisticConcurrency = optimisticConcurrencyFields.indexOf(field.name) !== -1;
+            field.configure({ options, optimisticConcurrency, parserForType });
+        });
     }
     /**
      * Returns all fields of the structured type.
@@ -2677,7 +2685,7 @@ class ODataStructuredTypeParser extends ODataAnnotatable {
         }
         return schema;
     }
-    validate(attrs, { method, navigation = false, } = {}) {
+    validate(attrs, { method, navigation = false, }) {
         const errors = {};
         const fields = this.fields({
             include_navigation: true,
@@ -2995,8 +3003,10 @@ class ODataStructuredType extends ODataParserSchemaElement {
             if (this.parent !== undefined)
                 this.parent.children.push(this);
         }
+        const entitySet = this.api.findEntitySetForEntityType(this.type()) ?? this.api.findEntitySetForEntityType(this.type({ alias: true }));
         this.parser.configure({
             options,
+            entitySet,
             parserForType: (t) => this.api.parserForType(t),
         });
         if (this.model !== undefined) {
@@ -3180,7 +3190,7 @@ class ODataStructuredType extends ODataParserSchemaElement {
      * @param method Method to use for the process validation
      * @returns Object with the errors
      */
-    validate(attrs, { method, navigation = false, } = {}) {
+    validate(attrs, { method, navigation = false, }) {
         return this.parser.validate(attrs, { method, navigation });
     }
 }
@@ -3204,7 +3214,7 @@ class ODataSchema extends ODataAnnotatable {
         this.containers = (config.containers ?? []).map((config) => new ODataEntityContainer(config, this));
     }
     isNamespaceOf(type) {
-        return type.startsWith(this.namespace) ?? (this.alias && type.startsWith(this.alias));
+        return type.startsWith(this.namespace) || (this.alias != null && type.startsWith(this.alias));
     }
     get entitySets() {
         return this.containers.reduce((acc, container) => [...acc, ...container.entitySets], []);
@@ -5988,8 +5998,7 @@ class ODataRequest {
         if (apiOptions.prefer?.maxPageSize !== undefined && ['GET'].indexOf(this._method) !== -1)
             prefer.push(`odata.maxpagesize=${apiOptions.prefer?.maxPageSize}`);
         // Annotations
-        if (apiOptions.prefer?.includeAnnotations !== undefined &&
-            ['GET'].indexOf(this._method) !== -1)
+        if (apiOptions.prefer?.includeAnnotations !== undefined && ['GET'].indexOf(this._method) !== -1)
             prefer.push(`odata.include-annotations=${apiOptions.prefer?.includeAnnotations}`);
         // Omit Null Values
         if (apiOptions.prefer?.omitNullValues === true && ['GET'].indexOf(this._method) !== -1)
@@ -10750,7 +10759,7 @@ class ODataCollection {
     }
     create(attrs = {}, { silent = false, server = true } = {}) {
         const model = this.modelFactory(attrs);
-        return (model.isValid() && server ? model.save() : of(model)).pipe(switchMap((model) => this.add(model, { silent, server })), map(() => model));
+        return (model.isValid({ method: 'create' }) && server ? model.save() : of(model)).pipe(switchMap((model) => this.add(model, { silent, server })), map(() => model));
     }
     set(path, value, {}) {
         const pathArray = (Types.isArray(path) ? path : path.match(/([^[.\]])+/g));
@@ -11204,10 +11213,10 @@ class ODataModel {
     }
     // Validation
     _errors;
-    validate({ method, navigation = false, } = {}) {
+    validate({ method, navigation = false, }) {
         return this._meta.validate(this, { method, navigation });
     }
-    isValid({ method, navigation = false, } = {}) {
+    isValid({ method, navigation = false, }) {
         this._errors = this.validate({ method, navigation });
         if (this._errors !== undefined)
             this.events$.trigger(ODataModelEventType.Invalid, {
@@ -11338,7 +11347,7 @@ class ODataModel {
             resource instanceof ODataNavigationPropertyResource))
             return throwError(() => new Error('save: Resource type ODataEntityResource/ODataNavigationPropertyResource needed'));
         // Resolve method and resource key
-        if (method === undefined && this.schema().isCompoundKey())
+        if (method === undefined && this.isCompoundKey())
             return throwError(() => new Error('save: Composite key require a specific method, use create/update/modify'));
         method = method || (!resource.hasKey() ? 'create' : 'update');
         if (resource instanceof ODataEntityResource &&
@@ -11415,6 +11424,9 @@ class ODataModel {
     isNew() {
         return !this._meta.hasKey(this);
     }
+    isCompoundKey() {
+        return this.schema().isCompoundKey();
+    }
     withResource(resource, ctx) {
         return this._meta.withResource(this, resource, ctx);
     }
@@ -11809,9 +11821,6 @@ class ODataModelField {
     parser;
     options;
     default;
-    required;
-    concurrency;
-    maxLength;
     minLength;
     min;
     max;
@@ -11823,9 +11832,6 @@ class ODataModelField {
         this.field = field;
         this.parser = parser;
         this.default = opts.default || parser.default;
-        this.required = Boolean(opts.required || !parser.nullable);
-        this.concurrency = Boolean(opts.concurrency);
-        this.maxLength = opts.maxLength || parser.maxLength;
         this.minLength = opts.minLength;
         this.min = opts.min;
         this.max = opts.max;
@@ -11843,16 +11849,20 @@ class ODataModelField {
     annotatedValue(term) {
         return this.parser.annotatedValue(term);
     }
-    configure({ concurrency, options }) {
+    configure({ options }) {
         this.parserOptions = options;
-        if (concurrency)
-            this.concurrency = concurrency;
         if (this.default !== undefined)
             this.default = this.deserialize(this.default, options);
     }
     isKey() {
         return this.parser.isKey();
     }
+    isComputed() {
+        return this.parser.isComputed();
+    }
+    isOptimisticConcurrency() {
+        return this.parser.isOptimisticConcurrency();
+    }
     hasReferentials() {
         return this.parser.hasReferentials();
     }
@@ -11882,7 +11892,7 @@ class ODataModelField {
             throw new Error(`Could not find enum type for ${this.parser.type}`);
         return enumType;
     }
-    validate(value, { method, navigation = false, } = {}) {
+    validate(value, { method, navigation = false, }) {
         if (ODataModelOptions.isModel(value)) {
             return !value.isValid({ method, navigation }) ? value._errors : undefined;
         }
@@ -11892,21 +11902,7 @@ class ODataModelField {
                 : undefined;
         }
         else {
-            const computed = this.annotatedValue(COMPUTED);
             const errors = this.parser?.validate(value, { method, navigation }) ?? [];
-            if (this.required &&
-                (value === null || (value === undefined && method !== 'modify')) && // Is null or undefined without patch?
-                !(computed && method === 'create') // Not (Is Computed field and create) ?
-            ) {
-                if (errors.indexOf('required') === -1)
-                    errors.push(`required`);
-            }
-            if (this.maxLength !== undefined &&
-                typeof value === 'string' &&
-                value.length > this.maxLength) {
-                if (errors.indexOf('maxlength') === -1)
-                    errors.push(`maxlength`);
-            }
             if (this.minLength !== undefined &&
                 typeof value === 'string' &&
                 value.length < this.minLength) {
@@ -12010,11 +12006,11 @@ class ODataModelAttribute {
     get navigation() {
         return this._field.navigation;
     }
-    get computed() {
-        return this._field.annotatedValue(COMPUTED);
+    isComputed() {
+        return this._field.isComputed();
     }
-    get concurrency() {
-        return Boolean(this._field.concurrency);
+    isOptimisticConcurrency() {
+        return this._field.isOptimisticConcurrency();
     }
     get referentials() {
         return this._field.referentials;
@@ -12184,17 +12180,7 @@ class ODataModelOptions {
                 this.parent.children.push(this);
         }
         this.entitySet = this.api.findEntitySetForEntityType(this.type());
-        let concurrencyFields = [];
-        if (this.entitySet !== undefined) {
-            concurrencyFields = this.entitySet.annotatedValue(OPTIMISTIC_CONCURRENCY) ?? [];
-        }
-        this._fields.forEach((field) => {
-            const concurrency = concurrencyFields.indexOf(field.field) !== -1;
-            field.configure({
-                concurrency,
-                options,
-            });
-        });
+        this._fields.forEach((field) => field.configure({ options, }));
     }
     fields({ include_navigation, include_parents, }) {
         return [
@@ -12252,8 +12238,7 @@ class ODataModelOptions {
             parser: structuredFieldParser,
         });
         modelField.configure({
-            options: this.api.options,
-            concurrency: false,
+            options: this.api.options
         });
         Object.defineProperty(self, modelField.name, {
             configurable: true,
@@ -12450,7 +12435,7 @@ class ODataModelOptions {
             return null;
         return resolve ? Objects.resolveKey(referenced, { single }) : Object.fromEntries(referenced);
     }
-    validate(self, { method, navigation = false, } = {}) {
+    validate(self, { method, navigation = false, }) {
         const errors = this.fields({
             include_parents: true,
             include_navigation: navigation,
@@ -12517,9 +12502,9 @@ class ODataModelOptions {
             .reduce((acc, attr) => {
             const name = field_mapping ? attr.fieldName : attr.name;
             let value = attr.get();
-            const computed = attr.computed;
+            const computed = attr.isComputed();
             const navigation = attr.navigation;
-            const concurrency = attr.concurrency;
+            const concurrency = attr.isOptimisticConcurrency();
             if (ODataModelOptions.isModel(value)) {
                 value = value.toEntity({
                     client_id,
@@ -13036,7 +13021,7 @@ class ODataApi {
         });
         return true;
     }
-    populate({ schemas, references, models, collections }) {
+    populate({ schemas, references, models, collections, }) {
         const odataSchemas = (schemas ?? []).map((schema) => new ODataSchema(schema, this));
         //TODO: Merge duplicates
         this.schemas = [...this.schemas, ...odataSchemas];