Merge pull request #65 from scimmyjs/issue/63-typescript-type-fixes

Refine TypeScript types and address type resolution issues

Author: sleelin

package-lock.json

@@ -12,12 +12,24 @@
   "types": "./dist/scimmy.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/scimmy.js",
-      "require": "./dist/cjs/scimmy.cjs"
+      "import": {
+        "types": "./dist/scimmy.d.ts",
+        "default": "./dist/scimmy.js"
+      },
+      "require": {
+        "types": "./dist/scimmy.d.ts",
+        "default": "./dist/cjs/scimmy.cjs"
+      }
     },
     "./*": {
-      "import": "./dist/lib/*.js",
-      "require": "./dist/cjs/lib/*.js"
+      "import": {
+        "types": "./dist/scimmy.d.ts",
+        "default": "./dist/lib/*.js"
+      },
+      "require": {
+        "types": "./dist/scimmy.d.ts",
+        "default": "./dist/cjs/lib/*.js"
+      }
     }
   },
   "scripts": {
@@ -70,7 +82,7 @@
     "jsdoc": "^4.0.2",
     "minimist": "^1.2.8",
     "mocha": "^10.4.0",
-    "ostensibly-typed": "^1.0.3",
+    "ostensibly-typed": "^1.2.0",
     "rollup": "^4.25.0",
     "sinon": "^19.0.2",
     "typescript": "^5.4.5"

package.json

@@ -192,14 +192,6 @@ export class Packager {
         const input = {[entry]: path.join(src, `${entry}.js`), ...chunks.reduce((chunks, chunk) => Object.assign(chunks, {[chunk]: path.join(src, `${chunk}.js`)}), {})};
         const manualChunks = chunks.reduce((chunks, chunk) => Object.assign(chunks, {[chunk]: [path.join(src, `${chunk}.js`)]}), {});
         const output = [];
-        const config = {
-            exports: "named", interop: "auto",
-            minifyInternalExports: false,
-            hoistTransitiveImports: false,
-            manualChunks, generatedCode: {
-                constBindings: true
-            }
-        };
 
         // Prepare RollupJS bundle with supplied entry points
         const bundle = await rollup.rollup({
@@ -210,8 +202,15 @@ export class Packager {
         // Construct the bundles with specified chunks in specified formats and write to destination
         for (let format of ["esm", "cjs"]) {
             const {output: results} = await bundle.write({
-                ...config, format, dir: (format === "esm" ? dest : `${dest}/${format}`),
-                entryFileNames: fileNameConfig[format], chunkFileNames: fileNameConfig[format]
+                format, exports: "named", interop: "auto",
+                dir: (format === "esm" ? dest : `${dest}/${format}`),
+                entryFileNames: fileNameConfig[format],
+                chunkFileNames: fileNameConfig[format],
+                minifyInternalExports: false,
+                hoistTransitiveImports: false,
+                manualChunks, generatedCode: {
+                    constBindings: true
+                }
             });
 
             output.push(...results.map(file => (format === "esm" ? file.fileName : `${format}/${file.fileName}`)));
@@ -234,7 +233,7 @@ export class Packager {
 
         // Prepare RollupJS with OstensiblyTyped plugin and supplied entry point
         const bundle = await rollup.rollup({
-            external, input: path.join(src, `${entry}.js`), 
+            external, input: path.join(src, `${entry}.js`),
             plugins: [generateDeclarations({moduleName: entry, defaultExport: "SCIMMY"})],
             onwarn: (warning, warn) => (warning.code !== "CIRCULAR_DEPENDENCY" ? warn(warning) : false)
         });

packager.js

@@ -34,16 +34,27 @@ export class BulkRequest {
     #dispatched = false;
 
     /**
-     * Instantiate a new SCIM BulkResponse message from the supplied BulkRequest
+     * BulkRequest operation details
+     * @typedef {Object} SCIMMY.Messages.BulkRequest~BulkOpOperation
+     * @property {SCIMMY.Messages.BulkRequest~ValidBulkMethods} method - the HTTP method used for the requested operation
+     * @property {String} [bulkId] - the transient identifier of a newly created resource, unique within a bulk request and created by the client
+     * @property {String} [version] - resource version after operation has been applied
+     * @property {String} [path] - the resource's relative path to the SCIM service provider's root
+     * @property {Object} [data] - the resource data as it would appear for the corresponding single SCIM HTTP request
+     * @inner
+     */
+    
+    /**
+     * Instantiate a new SCIM BulkRequest message from the supplied operations
      * @param {Object} request - contents of the BulkRequest operation being performed
-     * @param {Object[]} request.Operations - list of SCIM-compliant bulk operations to apply
+     * @param {SCIMMY.Messages.BulkRequest~BulkOpOperation[]} request.Operations - list of SCIM-compliant bulk operations to apply
      * @param {Number} [request.failOnErrors] - number of error results to encounter before aborting any following operations
      * @param {Number} [maxOperations] - maximum number of operations supported in the request, as specified by the service provider
-     * @property {Object[]} Operations - list of operations in this BulkRequest instance
+     * @property {SCIMMY.Messages.BulkRequest~BulkOpOperation[]} Operations - list of operations in this BulkRequest instance
      * @property {Number} [failOnErrors] - number of error results a service provider should tolerate before aborting any following operations
      */
     constructor(request, maxOperations = 0) {
-        let {schemas = [], Operations: operations = [], failOnErrors = 0} = request ?? {};
+        const {schemas = [], Operations: operations = [], failOnErrors = 0} = request ?? {};
 
         // Make sure specified schema is valid
         if (schemas.length !== 1 || !schemas.includes(BulkRequest.#id))
@@ -69,7 +80,7 @@ export class BulkRequest {
     }
 
     /**
-     * Apply the operations specified by the supplied BulkRequest 
+     * Apply the operations specified by the supplied BulkRequest and return a new BulkResponse message
      * @param {typeof SCIMMY.Types.Resource[]} [resourceTypes] - resource type classes to be used while processing bulk operations, defaults to declared resources
      * @param {*} [ctx] - any additional context information to pass to the ingress, egress, and degress handlers
      * @returns {SCIMMY.Messages.BulkResponse} a new BulkResponse Message instance with results of the requested operations 

src/lib/messages/bulkrequest.js

@@ -14,15 +14,45 @@ export class BulkResponse {
      */
     static #id = "urn:ietf:params:scim:api:messages:2.0:BulkResponse";
 
+    /**
+     * BulkResponse operation response status codes
+     * @enum {200|201|204|307|308|400|401|403|404|409|412|500|501} SCIMMY.Messages.BulkResponse~ResponseStatusCodes
+     * @inner
+     */
+    
+    /**
+     * BulkResponse operation details for a given BulkRequest operation
+     * @typedef {Object} SCIMMY.Messages.BulkResponse~BulkOpResponse
+     * @property {String} [location] - canonical URI for the target resource of the operation
+     * @property {SCIMMY.Messages.BulkRequest~ValidBulkMethods} method - the HTTP method used for the requested operation
+     * @property {String} [bulkId] - the transient identifier of a newly created resource, unique within a bulk request and created by the client
+     * @property {String} [version] - resource version after operation has been applied
+     * @property {SCIMMY.Messages.BulkResponse~ResponseStatusCodes} status - the HTTP response status code for the requested operation
+     * @property {Object} [response] - the HTTP response body for the specified request operation
+     * @inner
+     */
+    
+    /**
+     * Instantiate a new outbound SCIM BulkResponse message from the results of performed operations
+     * @overload
+     * @param {SCIMMY.Messages.BulkResponse~BulkOpResponse[]} operations - results of performed operations
+     */
+    /**
+     * Instantiate a new inbound SCIM BulkResponse message instance from the received response
+     * @overload
+     * @param {Object} request - contents of the received BulkResponse message
+     * @param {SCIMMY.Messages.BulkResponse~BulkOpResponse[]} request.Operations - list of SCIM-compliant bulk operation results
+     */
     /**
      * Instantiate a new SCIM BulkResponse message from the supplied Operations
-     * @param {Object|Object[]} request - contents of the BulkResponse if object, or results of performed operations if array
-     * @param {Object[]} [request.Operations] - list of applied SCIM-compliant bulk operation results, if request is an object
-     * @property {Object[]} Operations - list of BulkResponse operation results
+     * @param {SCIMMY.Messages.BulkResponse~BulkOpResponse[]} request - results of performed operations if array
+     * @param {Object} request - contents of the received BulkResponse message if object
+     * @param {SCIMMY.Messages.BulkResponse~BulkOpResponse[]} request.Operations - list of SCIM-compliant bulk operation results
+     * @property {SCIMMY.Messages.BulkResponse~BulkOpResponse[]} Operations - list of BulkResponse operation results
      */
     constructor(request = []) {
-        let outbound = Array.isArray(request),
-            operations = (outbound ? request : request?.Operations ?? []);
+        const outbound = Array.isArray(request);
+        const operations = (outbound ? request : request?.Operations ?? []);
 
         // Verify the BulkResponse contents are valid
         if (!outbound && Array.isArray(request?.schemas) && (!request.schemas.includes(BulkResponse.#id) || request.schemas.length > 1))

src/lib/messages/bulkresponse.js

@@ -36,11 +36,11 @@ export class ErrorResponse extends Error {
     static #id = "urn:ietf:params:scim:api:messages:2.0:Error";
 
     /**
+     * Details of the underlying cause of the error response
      * @typedef {Object} SCIMMY.Messages.ErrorResponse~CauseDetails
      * @property {SCIMMY.Messages.ErrorResponse~ValidStatusCodes} [status=500] - HTTP status code to be sent with the error
      * @property {SCIMMY.Messages.ErrorResponse~ValidScimTypes} [scimType] - the SCIM detail error keyword as per [RFC7644§3.12]{@link https://datatracker.ietf.org/doc/html/rfc7644#section-3.12}
      * @property {String} [detail] - a human-readable description of what caused the error to occur
-     * @internal
      * @inner
      */
 

src/lib/messages/error.js

@@ -12,13 +12,19 @@ export class ListResponse {
      */
     static #id = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
 
+    /**
+     * ListResponse sort and pagination constraints
+     * @typedef {Object} SCIMMY.Messages.ListResponse~ListConstraints
+     * @property {String} [sortBy] - the attribute to sort results by, if any
+     * @property {String} [sortOrder="ascending"] - the direction to sort results in, if sortBy is specified
+     * @property {Number} [startIndex=1] - offset index that items start from
+     * @property {Number} [count=20] - maximum number of items returned in this list response
+     */
+    
     /**
      * Instantiate a new SCIM List Response Message with relevant details
      * @param {Object|SCIMMY.Types.Schema[]} request - contents of the ListResponse message, or items to include in the list response
-     * @param {Object} [params] - parameters for the list response (i.e. sort details, start index, and items per page)
-     * @param {String} [params.sortBy] - the attribute to sort results by, if any
-     * @param {String} [params.sortOrder="ascending"] - the direction to sort results in, if sortBy is specified
-     * @param {Number} [params.startIndex=1] - offset index that items start from
+     * @param {SCIMMY.Messages.ListResponse~ListConstraints} [params] - parameters for the list response (i.e. sort details, start index, and items per page)
      * @param {Number} [params.count=20] - alias property for itemsPerPage, used only if itemsPerPage is unset
      * @param {Number} [params.itemsPerPage=20] - maximum number of items returned in this list response
      * @property {Array<Object|SCIMMY.Types.Schema>} Resources - resources included in the list response

src/lib/messages/listresponse.js

@@ -34,6 +34,11 @@ export class Group extends Types.Resource {
         return Schemas.Group;
     }
 
+    /** @implements {SCIMMY.Types.Resource.extend<typeof SCIMMY.Resources.Group>} */
+    static extend(...args) {
+        return super.extend(...args);
+    }
+    
     /** @private */
     static #ingress = () => {
         throw new Types.Error(501, null, "Method 'ingress' not implemented by resource 'Group'");

src/lib/resources/group.js

@@ -34,6 +34,11 @@ export class User extends Types.Resource {
         return Schemas.User;
     }
 
+    /** @implements {SCIMMY.Types.Resource.extend<typeof SCIMMY.Resources.User>} */
+    static extend(...args) {
+        return super.extend(...args);
+    }
+    
     /** @private */
     static #ingress = () => {
         throw new Types.Error(501, null, "Method 'ingress' not implemented by resource 'User'");

src/lib/resources/user.js

@@ -8,6 +8,11 @@ import Types from "../types.js";
  * *   Can be used directly, but is typically used to extend the `SCIMMY.Schemas.User` schema definition.
  */
 export class EnterpriseUser extends Types.Schema {
+    /** @type {"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"} */
+    static get id() {
+        return EnterpriseUser.#definition.id;
+    }
+    
     /** @implements {SCIMMY.Types.Schema.definition} */
     static get definition() {
         return EnterpriseUser.#definition;

src/lib/schemas/enterpriseuser.js

@@ -7,6 +7,11 @@ import Types from "../types.js";
  * *   Ensures a Group instance conforms to the Group schema set out in [RFC7643§4.2](https://datatracker.ietf.org/doc/html/rfc7643#section-4.2).
  */
 export class Group extends Types.Schema {
+    /** @type {"urn:ietf:params:scim:schemas:core:2.0:Group"} */
+    static get id() {
+        return Group.#definition.id;
+    }
+    
     /** @implements {SCIMMY.Types.Schema.definition} */
     static get definition() {
         return Group.#definition;

src/lib/schemas/group.js

@@ -7,6 +7,11 @@ import Types from "../types.js";
  * *   Ensures a ResourceType instance conforms to the ResourceType schema set out in [RFC7643§6](https://datatracker.ietf.org/doc/html/rfc7643#section-6).
  */
 export class ResourceType extends Types.Schema {
+    /** @type {"urn:ietf:params:scim:schemas:core:2.0:ResourceType"} */
+    static get id() {
+        return ResourceType.#definition.id;
+    }
+    
     /** @implements {SCIMMY.Types.Schema.definition} */
     static get definition() {
         return ResourceType.#definition;

src/lib/schemas/resourcetype.js

@@ -7,15 +7,19 @@ import Types from "../types.js";
  * *   Ensures a ServiceProviderConfig instance conforms to the Service Provider Configuration schema set out in [RFC7643§5](https://datatracker.ietf.org/doc/html/rfc7643#section-5).
  */
 export class ServiceProviderConfig extends Types.Schema {
+    /** @type {"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"} */
+    static get id() {
+        return ServiceProviderConfig.#definition.id;
+    }
+    
     /** @implements {SCIMMY.Types.Schema.definition} */
     static get definition() {
         return ServiceProviderConfig.#definition;
     }
 
     /** @private */
     static #definition = new Types.SchemaDefinition(
-        "ServiceProviderConfig", "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig",
-        "Schema for representing the service provider's configuration", [
+        "ServiceProviderConfig", "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig", "Schema for representing the service provider's configuration", [
             new Types.Attribute("reference", "documentationUri", {mutable: false, referenceTypes: ["external"], description: "An HTTP-addressable URL pointing to the service provider's human-consumable help documentation."}),
             new Types.Attribute("complex", "patch", {required: true, mutable: false, uniqueness: false, description: "A complex type that specifies PATCH configuration options."}, [
                 new Types.Attribute("boolean", "supported", {required: true, mutable: false, description: "A Boolean value specifying whether or not the operation is supported."})