rspec/rules/S3001/javascript/rule.adoc

== Why is this an issue?

The `delete` operator is used to remove a property from an object. It only affects its https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwn[own] properties. There are two valid ways to remove a property:

* Using the dot notation: `delete object.property`
* Using the bracket notation: `delete object[property]`

`delete` will throw a `TypeError` in strict mode if the property is a non-configurable property.

`delete identifier` may work if `identifier` is a *configurable* property of the global object. For `identifier` to be *configurable*, it should have been declared directly as a `globalThis` property (`globalThis.identifier = 1`). This form is not common practice and should be avoided. Use `delete globalThis.identifier` instead if needed.

Aside from that case, deleting variables, including function parameters, never works:

* Variables declared with `var` cannot be deleted from the global or a function's scope, because while they may be attached to the global object, they are *non-configurable*. In CommonJS and ECMAScript modules, top-level variable declarations are scoped to the module and not attached to the global object. 
* Variables declared with `let` or `const` are not attached to any object.

[source,javascript]
----
var x = 1;
delete x; // Noncompliant: depending on the context, this does nothing or throws TypeError

function foo(){}
delete foo; // Noncompliant: depending on the context, this does nothing or throws TypeError
----

Avoid using the `delete identifier` form. Instead, use one of the valid forms.

[source,javascript]
----
var obj = {
  x: 1,
  foo: function(){
  ...
  }
};
delete obj['x'];
delete obj.foo;
----


== Resources

=== Documentation

* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete[`delete` operator]
* MDN web docs - https://developer.mozilla.org/en-US/docs/Glossary/Global_object[Global object]
* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis[`globalThis`]
* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules[ECMAScript modules]
* Node.js Documentation - https://nodejs.org/api/modules.html[CommonJS modules]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Remove this "delete" operator or pass an object property to it.


=== Highlighting

* Primary: entire ``++delete++`` expression


'''
== Comments And Links
(visible only on this page)

=== on 4 Jun 2015, 12:13:03 Elena Vilchik wrote:
\[~ann.campbell.2] Assign to you for validation and completion (labels, SQALE). CC [~linda.martin]

=== on 4 Jun 2015, 14:10:16 Ann Campbell wrote:
\[~elena.vilchik] I've updated the description based on \https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete, which shows that _sometimes_ ``++delete++`` does work on things that might be thought of as variables (even though they're really properties of the global object.)


Let me know if it's not okay

endif::env-github,rspecator-view[]