Shakedown Social

Egor KloosI love that I can add CSS custom properties to a Custom Element Manifest via JSDoc. Let's see if I can add the idents/keys as specific properties to a JSX style attribute object. <a href="https://mastodon.social/tags/css" class="mention hashtag" rel="nofollow noopener" target="_blank">#css</a> <a href="https://mastodon.social/tags/jsdoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#jsdoc</a> <a href="https://mastodon.social/tags/cem" class="mention hashtag" rel="nofollow noopener" target="_blank">#cem</a> <a href="https://mastodon.social/tags/webcomponents" class="mention hashtag" rel="nofollow noopener" target="_blank">#webcomponents</a>

Aral BalkanWhile working on porting the Small Technology Foundation web site¹ to Kitten², I took the opportunity to pull out base Model and Collection classes that I’ll likely end up including in Kitten proper:• Model: <a href="https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/Model.js" rel="nofollow noopener" translate="no" target="_blank">https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/Model.js</a> • Collection: <a href="https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/Collection.js" rel="nofollow noopener" translate="no" target="_blank">https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/Collection.js</a>To see them in use, here’s the base Posts class (with RSS generation) that extends Collection: <a href="https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/Posts.js" rel="nofollow noopener" translate="no" target="_blank">https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/Posts.js</a> And here’s the concrete EventPosts collection class that extends Posts: <a href="https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/EventPosts.js" rel="nofollow noopener" translate="no" target="_blank">https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/EventPosts.js</a>And the EventPost (showing an implementation of a calculated property): <a href="https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/EventPost.js" rel="nofollow noopener" translate="no" target="_blank">https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/EventPost.js</a>So all this is possible (persisting and reading back typed model collections, etc.) thanks to JSDB¹ (JavaScript database), a zero-dependency, transparent, in-memory, streaming write-on-update JavaScript database I wrote for the Small Web that persists to a JavaScript transaction log and is included as as first-class citizen in Kitten.<a href="https://codeberg.org/small-tech/jsdb" rel="nofollow noopener" translate="no" target="_blank">https://codeberg.org/small-tech/jsdb</a>And if you want to know how the magic mapping of classes happens, see the Database App Module:<a href="https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/database.js#L34" rel="nofollow noopener" translate="no" target="_blank">https://codeberg.org/small-tech/site/src/branch/kitten/app_modules/database/database.js#L34</a>PS. For a much gentler introduction to persistence in Kitten, see the Kitten Persistence tutorial: <a href="https://kitten.small-web.org/tutorials/persistence/" rel="nofollow noopener" translate="no" target="_blank">https://kitten.small-web.org/tutorials/persistence/</a>Enjoy! :kitten:💕¹ <a href="https://small-tech.org" rel="nofollow noopener" translate="no" target="_blank">https://small-tech.org</a> ² <a href="https://kitten.small-web.org" rel="nofollow noopener" translate="no" target="_blank">https://kitten.small-web.org</a><a href="https://mastodon.ar.al/tags/Kitten" class="mention hashtag" rel="nofollow noopener" target="_blank">#Kitten</a> <a href="https://mastodon.ar.al/tags/SmallWeb" class="mention hashtag" rel="nofollow noopener" target="_blank">#SmallWeb</a> <a href="https://mastodon.ar.al/tags/SmallTech" class="mention hashtag" rel="nofollow noopener" target="_blank">#SmallTech</a> <a href="https://mastodon.ar.al/tags/JavaScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#JavaScript</a> <a href="https://mastodon.ar.al/tags/database" class="mention hashtag" rel="nofollow noopener" target="_blank">#database</a> <a href="https://mastodon.ar.al/tags/JSDB" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDB</a> <a href="https://mastodon.ar.al/tags/typeSafety" class="mention hashtag" rel="nofollow noopener" target="_blank">#typeSafety</a> <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> <a href="https://mastodon.ar.al/tags/closureCompiler" class="mention hashtag" rel="nofollow noopener" target="_blank">#closureCompiler</a> <a href="https://mastodon.ar.al/tags/TypeScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#TypeScript</a> <a href="https://mastodon.ar.al/tags/workInProgress" class="mention hashtag" rel="nofollow noopener" target="_blank">#workInProgress</a>

Aral BalkanAlmost another year has passed and it’s still not possible to use JSDoc and have the TypeScript LSP understand when you’re referring to a class and when you’re referring to an instance…*sigh*<a href="https://github.com/jsdoc/jsdoc/issues/1349#issuecomment-1725400751" rel="nofollow noopener" translate="no" target="_blank">https://github.com/jsdoc/jsdoc/issues/1349#issuecomment-1725400751</a><a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> <a href="https://mastodon.ar.al/tags/TypeScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#TypeScript</a> <a href="https://mastodon.ar.al/tags/web" class="mention hashtag" rel="nofollow noopener" target="_blank">#web</a> <a href="https://mastodon.ar.al/tags/dev" class="mention hashtag" rel="nofollow noopener" target="_blank">#dev</a>

🧿🪬🍄🌈🎮💻🚲🥓🎃💀🏴🛻🇺🇸If using Typescript means you want to write less Unit Tests then, actually, I'm all for it. Type away, with JSDoc comments.But I'm still making you write end-to-end functional browser tests. <a href="https://mastodon.social/tags/typescript" class="mention hashtag" rel="nofollow noopener" target="_blank">#typescript</a> <a href="https://mastodon.social/tags/unitTests" class="mention hashtag" rel="nofollow noopener" target="_blank">#unitTests</a> <a href="https://mastodon.social/tags/javaScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#javaScript</a> <a href="https://mastodon.social/tags/types" class="mention hashtag" rel="nofollow noopener" target="_blank">#types</a> <a href="https://mastodon.social/tags/typing" class="mention hashtag" rel="nofollow noopener" target="_blank">#typing</a> <a href="https://mastodon.social/tags/programming" class="mention hashtag" rel="nofollow noopener" target="_blank">#programming</a> <a href="https://mastodon.social/tags/webDev" class="mention hashtag" rel="nofollow noopener" target="_blank">#webDev</a> <a href="https://mastodon.social/tags/jsdoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#jsdoc</a> <a href="https://mastodon.social/tags/jsdocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#jsdocs</a>

Aral BalkanIf you use a parameter object in JavaScript, even if you specify its shape using JSDoc, you’ll only get errors if required properties are missing; not if there are extra properties provided.e.g.,```js class A { /** @param {{ id:string }} params */ constructor (params) { Object.assign(this, params) } }// Error: new A({})// No error: new A({id: 'x', foo:'bar'}) ```According to this thread, it’s a fact-of-life: <a href="https://stackoverflow.com/questions/49580725/is-it-possible-to-restrict-typescript-object-to-contain-only-properties-defined" rel="nofollow noopener" translate="no" target="_blank">https://stackoverflow.com/questions/49580725/is-it-possible-to-restrict-typescript-object-to-contain-only-properties-defined</a><a href="https://mastodon.ar.al/tags/JavaScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#JavaScript</a> <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a>

🧿🪬🍄🌈🎮💻🚲🥓🎃💀🏴🛻🇺🇸> JSR motivates best practices in code distribution—higher scores are awarded to packages that include comprehensive JSDoc documentation on each exported symbol<a href="https://deno.com/blog/jsr-is-not-another-package-manager" rel="nofollow noopener" translate="no" target="_blank">https://deno.com/blog/jsr-is-not-another-package-manager</a><a href="https://mastodon.social/tags/jsr" class="mention hashtag" rel="nofollow noopener" target="_blank">#jsr</a> <a href="https://mastodon.social/tags/webDev" class="mention hashtag" rel="nofollow noopener" target="_blank">#webDev</a> <a href="https://mastodon.social/tags/javaScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#javaScript</a> <a href="https://mastodon.social/tags/nodejs" class="mention hashtag" rel="nofollow noopener" target="_blank">#nodejs</a> <a href="https://mastodon.social/tags/typescript" class="mention hashtag" rel="nofollow noopener" target="_blank">#typescript</a> <a href="https://mastodon.social/tags/jsdoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#jsdoc</a> <a href="https://mastodon.social/tags/types" class="mention hashtag" rel="nofollow noopener" target="_blank">#types</a> <a href="https://mastodon.social/tags/programming" class="mention hashtag" rel="nofollow noopener" target="_blank">#programming</a> <a href="https://mastodon.social/tags/technology" class="mention hashtag" rel="nofollow noopener" target="_blank">#technology</a>

Aral BalkanYeah, I have no idea how this is still an issue in JSDoc in 2023. It looks like the project is abandoned – which is a damn shame for those of us who want type safety without having to introduce a build step using TypeScript in our projects.<a href="https://github.com/jsdoc/jsdoc/issues/1349#issuecomment-1725400751" rel="nofollow noopener" target="_blank">https://github.com/jsdoc/jsdoc/issues/1349#issuecomment-1725400751</a><a href="https://mastodon.ar.al/tags/web" class="mention hashtag" rel="nofollow noopener" target="_blank">#web</a> <a href="https://mastodon.ar.al/tags/JS" class="mention hashtag" rel="nofollow noopener" target="_blank">#JS</a> <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> <a href="https://mastodon.ar.al/tags/typescript" class="mention hashtag" rel="nofollow noopener" target="_blank">#typescript</a> <a href="https://mastodon.ar.al/tags/microsoft" class="mention hashtag" rel="nofollow noopener" target="_blank">#microsoft</a> <a href="https://mastodon.ar.al/tags/lsp" class="mention hashtag" rel="nofollow noopener" target="_blank">#lsp</a>

Aral BalkanIf you’re using JSDoc to cast, say, a global object to a class, here’s how you do it (TL; DR: Use `typeof` – it wasn’t immediately clear to me).<a href="https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/66713#discussioncomment-7043990" rel="nofollow noopener" target="_blank">https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/66713#discussioncomment-7043990</a><a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> <a href="https://mastodon.ar.al/tags/JS" class="mention hashtag" rel="nofollow noopener" target="_blank">#JS</a> <a href="https://mastodon.ar.al/tags/web" class="mention hashtag" rel="nofollow noopener" target="_blank">#web</a> <a href="https://mastodon.ar.al/tags/dev" class="mention hashtag" rel="nofollow noopener" target="_blank">#dev</a>

Aral BalkanThis took me way too long to figure out…If your <a href="https://mastodon.ar.al/tags/js" class="mention hashtag" rel="nofollow noopener" target="_blank">#js</a> function takes a parameter object and uses spread syntax to collect arbitrary additional properties (rest) and you want to document it using <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a>, the syntax is:[p:string]:anye.g.,```js /** @param {{ state: import('./SetupState.script.js').default, [p:string]:any }} parameterObject @returns {string|string[]} html */ export default ({state, ...props}) => html`…` ```Solution by Alexander Lonberg <a href="https://stackoverflow.com/a/68567492" rel="nofollow noopener" target="_blank">https://stackoverflow.com/a/68567492</a>

Aral BalkanA little <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> tip:If you need to use a type definition in an external file multiple times, you don’t have to keep writing `import(…).type` over and over. Just create a new type definition in your local file and use that.e.g.,```js /** @typedef {import('./SetupState.js').SetupStateType} SetupStateType */const state = { domain: /** @type SetupStateType */ (new SetupState('Domain')), server: /** @type SetupStateType */ (new SetupState('Server')), … } ```<a href="https://mastodon.ar.al/tags/js" class="mention hashtag" rel="nofollow noopener" target="_blank">#js</a> <a href="https://mastodon.ar.al/tags/web" class="mention hashtag" rel="nofollow noopener" target="_blank">#web</a> <a href="https://mastodon.ar.al/tags/dev" class="mention hashtag" rel="nofollow noopener" target="_blank">#dev</a>

Simon MacDonald🚫 TypeScript: YAGNITypeScript! What is it good for? I wouldn’t go as far as to say “absolutely nothing” like the song. I’m not trying to start a war here. It certainly is widespread, with JetBrains estimating it has nearly tripled in popularity over the past six years. However, we are scientists and using popularity as a reason for adopting a new tool is an excellent way to commit a logical fallacy.<a href="https://mastodon.online/tags/typescript" class="mention hashtag" rel="nofollow noopener" target="_blank">#typescript</a> <a href="https://mastodon.online/tags/javascript" class="mention hashtag" rel="nofollow noopener" target="_blank">#javascript</a> <a href="https://mastodon.online/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> <a href="https://begin.com/blog/posts/2023-07-19-typescript-yagni" rel="nofollow noopener" translate="no" target="_blank">https://begin.com/blog/posts/2023-07-19-typescript-yagni</a>

Aral Balkan- <a href="https://mastodon.ar.al/tags/JavaScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#JavaScript</a> is a wonderfully dynamic language and its dynamic features afford you a great deal of expressiveness.- Strong typing is useful for catching errors before runtime.These two statements don’t have to be mutually exclusive.Instead of shackling yourself to <a href="https://mastodon.ar.al/tags/TypeScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#TypeScript</a>™ 2023™ Enterprise Edition™, you can use <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> to get the best of both worlds.Here, for example, I’m mixing a property into Polka request handlers and annotating it. My intent is clear and the type checker’s happy.

Aral BalkanPS. Some <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> <a href="https://mastodon.ar.al/tags/tips" class="mention hashtag" rel="nofollow noopener" target="_blank">#tips</a>:You can refer to types in other modules & annotate parameters inline.``` async createOrUpdate (/** @type import('stripe').Stripe */ stripe) { … } ```You can define custom types, use unions:``` @typedef {State & RegistrationFormProperties} RegistrationFormStateType ```You can cast (note the parentheses):``` state = /** @type RegistrationFormStateType */ (new RegistrationFormState()) ```For more advanced uses, see Closure Type System: <a href="https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System" rel="nofollow noopener" target="_blank">https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System</a>

Aral BalkanWant strong typing without a build process?(Hint: you don’t need to use TypeScript.)1. Use a modern editor like Helix Editor or VSCodium that supports the TypeScript Language Server (LSP). 2. Add this line to the top of your JavaScript file (without the backticks, if you see any):``` // @ts-check ```3. Go read up on JSDoc ;)¹ <a href="https://helix-editor.com" rel="nofollow noopener" target="_blank">https://helix-editor.com</a> ² <a href="https://jsdoc.app/about-getting-started.html" rel="nofollow noopener" target="_blank">https://jsdoc.app/about-getting-started.html</a><a href="https://mastodon.ar.al/tags/javaScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#javaScript</a> <a href="https://mastodon.ar.al/tags/typeSafety" class="mention hashtag" rel="nofollow noopener" target="_blank">#typeSafety</a> <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a> <a href="https://mastodon.ar.al/tags/lsp" class="mention hashtag" rel="nofollow noopener" target="_blank">#lsp</a> <a href="https://mastodon.ar.al/tags/HelixEditor" class="mention hashtag" rel="nofollow noopener" target="_blank">#HelixEditor</a> <a href="https://mastodon.ar.al/tags/typeScript" class="mention hashtag" rel="nofollow noopener" target="_blank">#typeScript</a> <a href="https://mastodon.ar.al/tags/web" class="mention hashtag" rel="nofollow noopener" target="_blank">#web</a> <a href="https://mastodon.ar.al/tags/dev" class="mention hashtag" rel="nofollow noopener" target="_blank">#dev</a>

Aral Balkan`SystemError` typedef for Node.js (gist)<a href="https://codeberg.org/aral/gists/src/branch/main/SystemError.md" rel="nofollow noopener" target="_blank">https://codeberg.org/aral/gists/src/branch/main/SystemError.md</a>Node.js doesn’t expose the `SystemError` class in any way. This JSDoc type definition works around this limitation.__Update:__ Yeah, Node.js should _really_ just expose the `SystemError` class because this is ridiculous.<a href="https://mastodon.ar.al/tags/NodeJS" class="mention hashtag" rel="nofollow noopener" target="_blank">#NodeJS</a> <a href="https://mastodon.ar.al/tags/codeberg" class="mention hashtag" rel="nofollow noopener" target="_blank">#codeberg</a> <a href="https://mastodon.ar.al/tags/gist" class="mention hashtag" rel="nofollow noopener" target="_blank">#gist</a> <a href="https://mastodon.ar.al/tags/JSDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#JSDoc</a>

Recent searches

Search options

Administered by:

Server stats:

#jsdoc